docs: the spec extractor renders what the docstrings say

Merged
H3
2mo ago
+182-83

Against main, because the spec is generated from main and the 1.1 pages are what these defects currently corrupt. Raised by cubic on utcp-specification #66 (six of its ten findings were this extractor).

Four defects in scripts/extract_required_docs.py

  1. A prose line with a colon that isn't a name: description pair was silently dropped — (note: …) sentences, a quoted URL after (e.g., any colon mid-sentence. Now ordinary text.
  2. Any line ending in a colon became a title-cased header, code spans included — Inheritance is controlled by inherit_env_vars: → **Inheritance Is Controlled By Inherit_Env_Vars**; def tool1(): inside an example → **Def Tool1()**. A header is now a known Google-style one or a short title of words/digits/spaces/hyphens.
  3. A docstring with no section header was never flushed — 62 REQUIRED docstrings rendered as *No … documentation available* (UtcpClient, every auth serializer, the plugin loader, all socket methods…). The bogus headers from (2) had been flushing some by accident; fixing (2) exposed it.
  4. Cross-reference links were inserted inside inline code spans, where Markdown shows literal brackets. Links now stop at code spans; the field-list placeholder backticks are unwrapped before the pass so fields keep their links.

Also: a class whose own docstring isn't REQUIRED but whose methods are now renders them (the index already counted them — the "1 methods" with an empty page), and index links are POSIX on every platform.

Two docstrings corrected

The CLI template claimed tool_args are "shell-quoted" — the mechanism is per-invocation environment variables, as the same docstring's Argument Substitution section explains. OAuth2Auth.cache_key is written so the class links and cache_key stays code.

Verification

Regenerated against the published docs/api: 43 pages change. I audited every removed line — each is a placeholder, a bogus header, a link-in-code-span or a mangled example fragment — and 360 lines of previously invisible documentation come back. Windows path separators aside, the untouched extractor reproduces the published pages exactly, so the diff is only these fixes.

🤖 Generated with Claude Code