docs: the spec extractor renders what the docstrings say - #110
Merged
Merged
Conversation
Security updates
security fixes
fix(openapi): preserve array-form (JSON Schema / OAS 3.1) examples
OAuth2: key token caches by the full credential configuration
Four defects in scripts/extract_required_docs.py, each surfacing as a wrong page in the generated spec (cubic, utcp-specification #66): - A prose line containing a colon that is not a 'name: description' pair was silently DROPPED: '(note: ...)' sentences, quoted URLs after '(e.g.', anything with a colon mid-sentence. Such a line is now ordinary text. - Any line ending in a colon became a title-cased section 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 and hyphens. - A docstring with no section header at all was never flushed, so 62 REQUIRED docstrings across the spec rendered as '*No ... documentation available*' (UtcpClient, every auth serializer, the plugin loader, all socket methods, ...). The bogus headers above had been flushing some of them by accident, which the fix exposed. - Cross-reference links were inserted inside inline code spans, where Markdown shows them as 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 is not REQUIRED but whose methods are now renders those methods (the index already counted them), and index links are POSIX paths on every platform. Two docstrings corrected on the way: the CLI template claimed tool_args are 'shell-quoted' - the mechanism is per-invocation environment variables, as the same docstring explains - and 'OAuth2Auth.cache_key' is now written so the class links and cache_key stays code. Regenerated against the published pages: 43 pages change; every removed line is a placeholder, a bogus header, a link-in-code-span or a mangled example fragment; 360 lines of previously invisible documentation come back. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
h3xxit
force-pushed
the
docs/extractor-fidelity
branch
from
September 16, 2026 12:06
58f4ab3 to
4aea6b4
Compare
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
All reported issues were addressed
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
Three findings from cubic on #110, each a heuristic that was right on the cases in front of me and wrong one step over: - The inline-code splitter closed a span at the first backtick run, so ``a`b`` ended at the inner tick and class names still inside the span were linked. A span now closes only on a run of the same length. - A bare URL line ("https://example.com") still parsed as a definition: "https" is short, alphanumeric and has no space. A definition has a space after its colon; a URL has "//". That is the whole difference, so it is the rule. - The header heuristic (short, words only) admitted "Use the following:" and rejected "Return Values (Complex):" or anything over 41 chars. A custom header is a Title-Cased line ending in a colon: every word starts with a capital or a digit, no code span, any length. Sentence- case captions ("Basic command step:") now stay under their real "Examples" header instead of replacing it. Unit-checked on the boundary cases; regenerated and compared with the previous run -- the only movement is captions becoming paragraphs under the section header they belong to. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Against
main, because the spec is generated frommainand 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.pyname: descriptionpair was silently dropped —(note: …)sentences, a quoted URL after(e.g., any colon mid-sentence. Now ordinary text.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.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.Also: a class whose own docstring isn't
REQUIREDbut 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_argsare "shell-quoted" — the mechanism is per-invocation environment variables, as the same docstring's Argument Substitution section explains.OAuth2Auth.cache_keyis written so the class links andcache_keystays 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