docs: make the guided tour execute (Phase E5) - #920
Merged
Merged
Conversation
…ur.jl) Every user-facing name for this page is "Guided tour" — the sidebar label, the H1, the `@id getting-started-guided-tour` anchor, and the generated `guided-tour.md` / `.ipynb` / `.jl` outputs. The Literate source was the last place still called `tutorial.jl`. Pure rename; `make.jl` updated to match, Literate output names unchanged. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…e E5) The guided tour was the last page still skipped at build time: `make.jl` carried a comment attributing the work to "PR 11" (long merged) and warning that executing it "surfaced several unrelated runtime bugs". Those bugs were upstream and have since been fixed across the ecosystem — the tour now builds clean. - make.jl: inject `Draft = false` into the generated page's `@meta` block via a Literate `postprocess`, so the tour's code runs under the global `draft = true` like every other real page. 21 `@example` blocks now execute; 6 figures render (SVG). - guided-tour.jl: two ordered lists rewritten. DocumenterVitepress mis-renders any ordered list whose items carry block content — valid `1. 2. 3.` source comes out `2. 3. 4.` (LuxDL/DocumenterVitepress.jl#150). "two ways" (cold start / cascade) → inline prose; "three steps" (maximising control / BVP / shooting) → `Step 1 — / Step 2 — / Step 3 —` bold-lead paragraphs, math blocks kept. Verified: full docs build exit 0, 0 unresolved @ref, no `<ol start=` in the built page. The GPU section is left as-is — it is the reference pattern tracked in #885. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Phase E5 of the documentation campaign: the guided tour
(
docs/src/getting-started/guided-tour.md, generated fromdocs/src-literate/guided-tour.jlvia Literate) was the last page stillskipped at build time.
make.jlcarried a stale comment attributing thework to "PR 11" (merged long ago) and warning that forcing execution
"surfaced several unrelated runtime bugs".
Those bugs were upstream and have since been fixed across the ecosystem over
the course of this campaign. The tour now builds clean.
Commits
docs/src-literate/tutorial.jl→guided-tour.jl— everyuser-facing name for this page is already "Guided tour" (sidebar, H1,
@id getting-started-guided-touranchor, generatedguided-tour.md/.ipynb/.jl). Pure rename, Literate output names unchanged.make.jl: injectDraft = falseinto the generated page's@metablock via a Literate
postprocess, so the tour's code runs under theglobal
draft = truelike every other real page. 21@exampleblocks execute; 6 SVG figures render.
guided-tour.jl: two ordered lists rewritten.LuxDL/DocumenterVitepress.jl#150
— DocumenterVitepress mis-renders any ordered list whose items carry
block content (
1. 2. 3.source →2. 3. 4.output). "two ways"(cold start / cascade) → inline prose; "three steps" →
Step 1 — / Step 2 — / Step 3 —bold-lead paragraphs.Not in scope
try/catchblock is thereference pattern named in
#885
(make
gpu.mdexecutable; a GPU-backed docs build).flows/overview.md, theapi/*docstring-sourced pages) — tracked separately; this PR only touches the
tour's two.
Verification
Full
julia --project=. docs/make.jlfrom repo root:Cannot resolve @ref(thegetting-started-guided-touranchor,referenced from
index.mdandfirst-problem.md, resolves)<ol start=anywhere inbuild/1/getting-started/guided-tour.html@extrefupstream-backlogitems (CTModels#416 / CTBase#543)
Add the
run documentationlabel to build the site in CI.🤖 Generated with Claude Code