docs: the spec extractor renders what the docstrings say
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
- A prose line with a colon that isn't a
name: descriptionpair was silently dropped —(note: …)sentences, a quoted URL after(e.g., any colon mid-sentence. Now ordinary text. - Any line ending in a colon became a title-cased header, code spans included —
Inheritance is controlled byinherit_env_vars:→**Inheritance Is Controlled ByInherit_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. - A docstring with no section header was never flushed — 62
REQUIREDdocstrings 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. - 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