SciML / SciML/FiniteVolumeMethod.jl

Literate regeneration emits malformed Markdown for multiline #src test calls

Open
#128 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Julia
Stars
52
Forks
8
Avg merge
1d 35m
Merged PRs (30d)
8

Description

origin/main (0ac4d92) contains multiline @test_reference calls whose final line carries #src, for example docs/src/literate_tutorials/diffusion_equation_on_an_annulus.jl:159-162.

Reproduction from a clean checkout:

LIVESERVER_ACTIVE=true julia +1.12 --project=docs -e 'using Pkg; Pkg.instantiate(); include("docs/make.jl")'

With the currently resolved Literate 2.21.0, regeneration writes incomplete @example and “Just the code” blocks. In docs/src/tutorials/diffusion_equation_on_an_annulus.md, the generated block retains:

@test_reference joinpath(
    @__DIR__, "../figures",
    "diffusion_equation_on_an_annulus_interpolated_with_naturalneighbours_bad.png"

The closing ) fig #src line is removed, making the generated Markdown invalid Julia. The pre-existing committed Markdown does not have this malformed fragment, so this is separate from the strict Documenter failures caused by stale solver imports.

Expected behavior: #src should suppress the full source-only test expression without emitting an incomplete partial expression, or the Literate sources should use a form that is stable under the current Literate release.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the multiline @test_reference calls in docs/src/literate_tutorials/diffusion_equation_on_an_annulus.jl, especially lines 159-162, and reproduce with the provided Julia docs/make.jl command. Compare the generated blocks in docs/src/tutorials/diffusion_equation_on_an_annulus.md with the committed Markdown. Done means regeneration no longer emits incomplete Julia from #src-marked calls, either through a stable source form or the expected Literate behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
julia
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.