SciML / SciML/FiniteVolumeMethod.jl
Literate regeneration emits malformed Markdown for multiline #src test calls
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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