docs: rewrite tooling in PHP, drop Python dependency

[adamziel]

Summary

The toolkit now documents itself using only its own runtime and its own structured-data parsers. No Python in CI; no hand-rolled regex over markdown or HTML.

What changed

Was	Now
bin/_docs_components.py (200 lines, dead-code dicts)	deleted
bin/_load_catalog.py (370 lines: hand-rolled YAML-subset parser, regex section splitter, regex snippet extractor)	replaced with proper parsers
bin/build-reference.py (220 lines)	bin/build-reference.php
bin/run-snippets.py (230 lines)	bin/run-snippets.php
bin/serve-docs.py (50 lines)	bin/serve-docs.php (uses php -S with router)

Parsers

Surface	Parser
README YAML frontmatter (slug, title, install, credit_*, see_also)	Webuni\FrontMatter\FrontMatter::parse() — already vendored under components/Markdown/vendor-patched/ for the Markdown component. Single-line, multi-line `key:
Markdown body → AST	League\CommonMark\Parser\MarkdownParser + walking the document. Section boundaries = Heading nodes at level 2. Snippets = HtmlBlock (<!-- snippet: -->) → FencedCode (info=php) tuples. Expected-output = HtmlBlock (<!-- expected-output -->) → FencedCode pair. Body content rendered via HtmlRenderer::renderNodes() so raw HTML round-trips verbatim.
Pitfall callouts (HtmlBlocks of the form <p>Footgun: …</p>)	WP_HTML_Tag_Processor — walks tokens, confirms a <p> opener, finds the first inner #text node, classifies, strips the Footgun: / Gotcha: prefix via set_modifiable_text(), then slices off the outer <p>...</p> by length (no regex).
Lede paragraph → inline HTML (no outer <p>)	Render the lede Paragraph node's inline children directly via HtmlRenderer::renderNodes() instead of slicing afterward.
Snippet metadata comment (<!-- snippet: filename: x.php\nrunnable: true\n-->)	String slicing of literal <!-- / --> delimiters — no regex.
--update writing captured stdout back into a README	CommonMark AST locates the snippet's exact line range; line-by-line splice. No regex over the README.

Behavioural parity

• 87/87 snippets match their captured stdout. The PHP normalizer mirrors the Python regex set 1:1, so existing expected-output blocks stay valid.
• docs/reference/*.html render correctly: 9 <php-snippet> + 9 fallback + 9 expected-output triples on html.html, 4 pitfall callouts (the bold-lead pattern is preserved), see-also list intact.
• --update verified end-to-end:
  • When an expected-output block has drifted, the rewritten content is byte-for-byte the original.
  • When no expected-output exists for a snippet, --update inserts a fresh block in the right place; resulting README is byte-identical to one with the block authored manually.

Frontmatter format change: see_also is a proper YAML list

# Before (repeated keys — not standard YAML)
see_also: a | A | reason
see_also: b | B | reason

# After
see_also:
  - a | A | reason
  - b | B | reason

Webuni\FrontMatter\FrontMatter correctly types it as a sequence; any frontmatter-aware tool reading the README sees the same shape. All 18 component READMEs migrated.

Workflows simplified

• snippet-tests.yml drops the actions/setup-python step.
• docs.yml swaps python3 bin/build-reference.py for php bin/build-reference.php.

Remaining preg_* calls (all on plain text, not HTML)

• slugify() — heading text → URL-safe slug.
• normalize() — scrubs noise from snippet stdout (tempfile paths, git hashes, timestamps).
• One pattern in run-snippets that matches the require '...autoload.php'; line in the snippet's PHP source to inject the local-prelude polyfill.

These operate on plain strings, not HTML, so they're not what the "no regex over HTML" rule was about.

Test plan

• Verify docs snippets workflow passes (87/87).
• Deploy docs to GitHub Pages runs cleanly on push to trunk.
• Local preview: bash bin/build-docs-bundle.sh && php bin/serve-docs.php — http://localhost:8787 renders all reference pages with snippets.
• php bin/run-snippets.php --update (no-op, no drift) leaves all READMEs untouched.

🤖 Generated with Claude Code