Skip to content

docs: finish the coherence pass (guided tour residue + logo/abstract-syntax line width) - #934

Merged
ocots merged 1 commit into
mainfrom
docs/coherence-pass-followup
Sep 1, 2026
Merged

docs: finish the coherence pass (guided tour residue + logo/abstract-syntax line width)#934
ocots merged 1 commit into
mainfrom
docs/coherence-pass-followup

Conversation

@ocots

@ocots ocots commented Sep 1, 2026

Copy link
Copy Markdown
Member

Follow-up to the E4 coherence pass (#917 / #918)

PR #918 (line wrapping, F16) explicitly deferred getting-started/guided-tour.md to Phase E5 because it is Literate-generated. Phase E5 (#920) made the tour execute but did not carry over the coherence-pass fixes, so two sub-items of the runbook's "coherence pass" step were left open. This closes them, plus two files that were touched after the wrap pass.

docs/src-literate/guided-tour.jl (source; .md / .ipynb / .jl are regenerated at build, not tracked)

  • F16 — six lines over 75 characters inside @example blocks:
    • constraint!(pre, :boundary; …), the two println("Ipopt/MadNLP …"), plot!(plt_bang[1], …) wrapped one group per line with a trailing comma;
    • two over-long trailing comments trimmed (has_abstract_definition, using OrdinaryDiffEqTsit5, and a ## note).
  • F25solve(prob; show_trace=Val(true))NonlinearSolve.solve(prob; …). This was the last shooting call site still calling solve unqualified after using NonlinearSolve; all examples/*.md and flows/shooting.md were already qualified.

docs/src/examples/logo.md

Four lines at 76–81 characters (post-dating the #918 wrap pass): circle(r) = […] and ax = Axis(…) wrapped; two padded comments narrowed.

docs/src/modelling/abstract-syntax.md

One 77-character comment line in an @example block trimmed (77 → 62).

Verification

  • Meta.parseall on the Literate source: OK.
  • Literate regeneration of guided-tour.md: 0 lines over 75 in @example / @repl / @setup blocks (was 6).
  • logo.md @example blocks: 5/5 parse clean.

Deliberately not touched

The remaining over-75 lines in fenced blocks are all documented exceptions:

🤖 Generated with Claude Code

…olve.solve

Phase E4 part 2 (#918) deferred getting-started/guided-tour.md to E5, and
E5 (#920) made it execute without applying the coherence fixes. Close the
gap at the Literate source:

- wrap the six over-75 lines in `@example` blocks (constraint!, the two
  println, plot!, trim two long comments);
- `solve(prob; …)` -> `NonlinearSolve.solve(prob; …)`, the last unqualified
  shooting call site (F25).

Also the two files touched after the wrap pass:

- examples/logo.md — four lines at 76-81 (circle, Axis, two padded
  comments), all brought within 75;
- modelling/abstract-syntax.md — one 77-char comment trimmed.

Verified: Literate regen of guided-tour.md has 0 lines over 75 in
executable blocks; logo.md example blocks parse clean.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@ocots
ocots merged commit aacbd3e into main Sep 1, 2026
3 checks passed
@ocots
ocots deleted the docs/coherence-pass-followup branch September 1, 2026 08:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant