SciML / SciML/FiniteVolumeMethod.jl
Generated tutorial Markdown is stale and Documenter failures are hidden by warnonly
Open
Nobody has claimed this yet.
- Dominant language
- Julia
- Stars
- 52
- Forks
- 8
- Avg merge
- 1d 35m
- Merged PRs (30d)
- 8
Description
Reproduction
On current origin/main (0ac4d92), run:
CI=true julia +1.12 --project=docs -e 'using Pkg; Pkg.instantiate(); include("docs/make.jl")'\n```\n\nThe command exits zero only because `docs/make.jl` passes `warnonly = true` to `makedocs`. It emits many `failed to run @example block` warnings before rendering. The first is `docs/src/tutorials/diffusion_equation_in_a_wedge_with_mixed_boundary_conditions.md:111-120`, where `TRBDF2` is undefined. Dependent blocks then fail because their setup did not complete.\n\n## Cause\n\nCommit `52dbed5` updated the Literate tutorial sources to import `OrdinaryDiffEqSDIRK`, but the committed generated Markdown retained `using OrdinaryDiffEq, LinearSolve`. This leaves `TRBDF2` unavailable. The same stale-import pattern affects other tutorial and WYOS pages; `wyos/diffusion_equations.md` and `wyos/linear_reaction_diffusion_equations.md` also need `SciMLOperators` for `MatrixOperator`.\n\nA focused generated-Markdown synchronization plus removing `warnonly` is straightforward, but current Literate regeneration is itself invalid: [#128](https://github.com/SciML/FiniteVolumeMethod.jl/issues/128) documents how multiline source-only `#src` lines produce malformed Markdown. Until that is fixed, regenerating these pages cannot be used as the source of truth.\n\n## Attribution\n\nThis reproduces directly on a clean current `origin/main`; it predates the SciMLTesting v2.4 migration. The old migration PR therefore exposed a baseline documentation problem rather than causing it.
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 docs/make.jl and the generated pages docs/src/tutorials/diffusion_equation_in_a_wedge_with_mixed_boundary_conditions.md, wyos/diffusion_equations.md, and wyos/linear_reaction_diffusion_equations.md. Run the documented CI=true Julia docs command, while reading issue #128 because current Literate regeneration produces malformed Markdown. Done means the generated imports are synchronized, required names resolve, and Documenter failures cause the build to fail rather than being hidden by warnonly.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- julia
- Domain
- build-system, documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 68/100