docs: page-by-page review of the documentation - #953
Draft
ocots wants to merge 1 commit into
Draft
Conversation
First page of the page-by-page documentation review.
index.md
- Motivation: one dense paragraph split into four.
- Basic usage: a transition line before the "each step has its own guide" list.
- Mathematical formulation: the Mayer term reworded as a boundary/pointwise cost
on the initial and final times and states and the optimisation variables, not
just the final state.
- Testing: one dense paragraph split into three.
- Reproducibility: dropped the `_downloads_toml` helper and three raw-HTML
`<details>` blocks (one emoji used twice); now a lead paragraph, a two-row
table for the two project files, and one `::: details` block holding
versioninfo / Pkg.status / Pkg.status(manifest).
Logo
- `logo.png` -> `logo.svg` (cropped artwork from .extras/logos/logo-gagnant/).
- Home page dark mode: an exact light/dark SVG pair. `docs/make.jl` generates
`logo-dark.svg` from `logo.svg` (white backdrop -> #1b1b1f, Julia colours
unchanged), git-ignored; two <img> with a plain display toggle.
- Navbar: single `/logo.svg` recoloured in dark mode by a `.dark` filter (24px,
the ~10% desaturation is imperceptible; a light/dark <img> pair double-renders
in the DocumenterVitepress navbar title).
Environment download (fixes a live 404 on the dev site)
- VitePress does not bundle `.toml` referenced from a Markdown link, so the
Project.toml / Manifest.toml download links have been 404 on `dev` since the
DocumenterVitepress migration. `docs/make.jl` now copies each into
`src/public/assets/` (served verbatim) as well as `src/assets/` (Documenter's
link check). `src/public/` is git-ignored.
Dark-mode figures
- `.dark .vp-doc img[alt=""] { filter: invert(0.894) hue-rotate(180deg) }` in
style.css: a = 1 - 27/255 lands white on the VitePress dark surface. Catches
every local `![]` image (DVP drops their alt); exclude one with a `@raw html`
`<img alt="...">`.
Plan and per-page log: .reports/documentation-review-2026-09.md (git-ignored).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Member
Author
|
Status: page 1/45 ( This first commit is larger than the following ones will be — besides the Next: |
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.
Page-by-page documentation review
A slow re-reading of every hand-written docs page, one at a time — prose, wording, coherence, links, small fixes. Not a rewrite (that closed with #942): the maintainer reads each rendered page, hands back changes, they get applied and validated, then the next page.
Draft until every page has been through. One commit per validated page.
Progress
index.mdMechanics
docs/make.jlstays atdraft = falsein every commit here. The review is done locally with the flag flipped totrue(fast — only the page under review executes, tagged with@meta Draft = false); neither the flip nor the tag is committed..reports/documentation-review-2026-09.md(git-ignored).This first commit also carries three infra fixes surfaced while reviewing
index.mddevsite. VitePress does not bundle.tomlreferenced from a Markdown link — the file never reachesdocs/build/1/.docs/make.jlnow also copiesProject.toml/Manifest.tomlintodocs/src/public/assets/(served verbatim). Written up inHandbook/VITEPRESS-DOC.md..png→.svg, with an exact light/dark SVG pair for dark mode on the home page (logo-dark.svggenerated bymake.jl), and a single filtered<img>in the navbar.filter: invert(0.894) hue-rotate(180deg)on@examplefigure output, landing the white ground on the#1b1b1fpage surface.Verified
julia --project=docs docs/make.jl— exit 0,@ref0, only the six tolerated upstream@extref. TOMLs served at/assets/*.toml; navbar + home logo adapt to the theme toggle.🤖 Generated with Claude Code