Skip to content

Verify doc outputs and tighten every docs page - #297

Merged
Chemaclass merged 9 commits into
masterfrom
docs/verified-outputs
Oct 28, 2026
Merged

Chemaclass merged 9 commits into
masterfrom
docs/verified-outputs

Conversation

@Chemaclass

@Chemaclass Chemaclass commented Oct 28, 2026 •

Copy link
Copy Markdown
Member

The docs hold hundreds of ; => value comments inside Phel code blocks, and the snippet suite only checked that each block runs. A wrong value could sit there for years. The suite now rewrites every form ; => value (or a ; => value line right below the form) into a check and fails on a mismatch, using the same baseline and ratchet it already has for blocks that cannot run. Mismatch reports start on a new line so output from print cannot hide a wrong result; an end-to-end regression covers this case. Lines whose expected text is not data (..., "instance", #') are skipped and listed under --verbose.

First value caught: (assoc p :x 10) on the data structures page said (point 10 2); Phel prints (user.point 10 2).

Also in this PR

  • npm run check:docs (scripts/check-docs.js) checks every docs page, and CI runs it: a description of 50 to 160 characters, a difficulty on every language page, ; => and ; prints with one semicolon, the callout component instead of a blockquote, no Phel release older than config.toml outside upgrading.md, a lead paragraph before the first H2, and no H1 in the body. The 21 pages that broke a rule are fixed. The error reference intro is now a plain paragraph, since that page skips templating and cannot use the callout.

  • CI runs npm run check:links after zola build. zola check only follows @/ links, and this site writes absolute ones.

  • Aliases for old URLs that 404 today: /documentation/guides/phel-for-php-developers, /documentation/language/arithmetic, /documentation/language/truth-and-boolean-operations, /documentation/numbers-and-arithmetic, /documentation/reference/one-liners, /documentation/debug, /documentation/debug/php-tools, /documentation/debug/phel-helpers, /documentation/commands, /documentation/tutorials, /documentation/tooling/authoring-libraries, /documentation/reference/in-the-wild. /documentation/guides/ai already redirects through static/.htaccess.

  • Each core language page links to its practice module: practice = [...] in the front matter renders one tip card at the end of the page.

  • Sidebar links no longer replay the slide-in animation on navigation. Sections open and close immediately, and link transitions only animate colors so collapsed links leave view and the tab order immediately.

Checked

  • composer test:snippets: 554 snippets pass, 869 documented values checked, 0 mismatches, empty baseline.

  • vendor/bin/phpunit (135 tests) and composer phpstan.

  • npm run check:docs: 0 problems. zola build, zola check --skip-external-links and npm run check:links: 9816 links, 0 broken.

  • Sidebar navigation and all six section toggles checked with mouse and keyboard at 1440px and 390px, in light and dark themes. No horizontal overflow.

  • CSS formatting passes. CSS lint has 50 existing errors in the two changed files, with no new errors.

The suite only proved that each block runs. It now rewrites every single-line form with a ; => comment into a check and fails on a mismatch, with the same baseline and ratchet used for blocks that cannot run.
npm run check:docs fails on a description outside 50 to 160 characters, a language page without a difficulty, ;; => or ;; prints, a blockquote, a Phel release older than config.toml outside upgrading.md, a page that opens with a heading, and an H1 in the body. CI runs it. The pages that broke a rule are fixed.
zola check only follows @/ links, and this site writes absolute ones.
A practice list in the front matter renders one tip card under the page.
@Chemaclass
Chemaclass marked this pull request as ready for review October 28, 2026 12:22
Comment thread build/run-doc-snippets.php Resolved
@Chemaclass
Chemaclass merged commit 2ff845c into master Oct 28, 2026
10 checks passed
@Chemaclass
Chemaclass deleted the docs/verified-outputs branch October 28, 2026 12:52
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