Retire the post-render docstring translators and link numbered citations - #333
Merged
rich-iannone merged 29 commits intoAug 31, 2026
Merged
Conversation
Post-render rebuilt unparsed section-like syntax as structured HTML. It now leaves that syntax as prose, allowing the docstring-style linter to report parser mismatches.
Post-render converted Sphinx roles in every project. Conversion now follows the configured docstring parser, leaving role syntax unchanged under the numpy and Google parsers.
Post-render rebuilt numbered RST citations as HTML lists. Docstrings now use the project bibliography, which applies the same numbering and formatting as prose pages.
Remove the CSS and HTML cleanup used only by the retired post-render section conversion. Parsed docstring sections retain their renderer-provided markup and styling.
Sphinx fixtures must render cross-reference roles as inline code and add parentheses to callable roles. NumPy fixtures must preserve the literal role syntax.
The rendered Raises section contains an independent exception annotation. Restrict the role assertions to prose so that annotation cannot hide a failed conversion.
Explain that callout and version directives work with every parser. Require the Sphinx parser for field lists, roles, numbered citations, and other Sphinx-specific forms, and document bibliography citations as the parser-independent alternative.
Use the fixture that previously triggered fabricated sections, require rendered pages before checking them, cover every Sphinx role and callable-parentheses case, and reject the retired section markup.
Describe the fixture as NumPy-style docstrings that use `[@citekey]` markers and a project bibliography. Remove references to the retired in-docstring References sections.
Move numbered RST citation conversion into parser-independent normalisation. Preserve citation labels, join wrapped bodies, autolink bare URLs, and leave nonnumeric labels unchanged.
Use one fixture for numbered citations defined in docstrings and another for `[@citekey]` markers resolved from a project bibliography. Verify each mechanism produces rendered references without leaking source syntax.
Document numbered citations defined in a docstring and `[@citekey]` markers resolved from a project bibliography. Clarify which citation syntax works with every parser and which RST forms still require the Sphinx parser.
Retain each marker's indentation. Join only following lines that are more deeply indented, keep adjacent markers separate, and accept citation bodies that start on the following line.
Read the expected surname from every fixture and require it inside a rendered citation list. Unrelated ordered lists can no longer satisfy the citation assertion, and Sphinx-role cases now share the implementation's role sets.
Link each `[N]_` reference to its citation. Add a return link for one reference or lettered return links for repeated references, preserve unmatched references as literal text, and scope anchors by object path.
Keep letters, digits, and underscores as written while replacing other character runs with hyphens. Object paths that differ only by case or by dot-versus-underscore separators now produce distinct anchors.
Require every citation and backlink target to exist on the same page, reject unconverted reference markers, and exercise lettered backlinks by citing one source twice.
Document `[N]_` references, their bidirectional links, and their same-docstring scope. Also clarify the blank-line requirement for Google-style section headers and keep parser-independent citation syntax separate from Sphinx-only RST.
Move unmatched trailing parentheses outside autolink angle brackets. Markdown link delimiters remain visible, while balanced parentheses that belong to a URL path remain inside the link.
Give citation-reference links their own class, footnote-reference role, and raised compact styling so readers can distinguish them from surrounding prose.
Wrap each reference number in a `sup` element so the browser supplies superscript positioning and sizing. Generate the surrounding brackets on that element so they rise with the number.
Wrap each citation body in the element targeted by its references so Quarto can populate the hover preview. Preserve body text unchanged and document that authors must escape unmatched brackets.
Recommend `%` callout and version directives for every parser. Continue recognising existing RST forms in NumPy and Google docstrings so older docstrings keep rendering.
Great Docs converted citation examples inside fenced blocks and inline code. References shown as code also increased backlink counts. This could replace one linked caret with lettered backlinks. Preserve citation definitions and references in fenced blocks, inline code spans, and unfenced doctest prompts. Exclude those references from backlink counts. Recognise RST section underlines and leading inline code spans without opening a fence. Citation conversion then continues in the prose that follows.
Document why alias paths cannot assign page-specific citation anchors during object resolution. Require rendering to combine page and object context so identical labels remain independent on multi-object pages.
Citation conversion stopped at the first blank line, so the citation anchor and Quarto hover preview contained only the first paragraph. Continue a citation body across blank lines while subsequent text remains indented beyond its marker. Render a multi-paragraph body as a block anchor and preserve relative indentation so nested lists retain their structure. Keep single-paragraph output unchanged. Hide backlinks in hover previews because the block anchor contains them.
Bare URLs in citation bodies previously consumed trailing sentence punctuation and adjacent citation-reference markup. End each autolink before Markdown delimiters, and move trailing punctuation outside its target. Preserve balanced parentheses in URL paths. Leave URLs inside inline code unchanged.
Default test runs skipped every rendered-output assertion unless a prebuilt Gauntlet site existed. Fresh checkouts therefore did not verify citation anchors, superscripts, backlinks, or deployed styles. When Quarto is available, build two existing citation fixtures before collection. Reuse existing sites, coordinate concurrent builds with per-package sentinels, and publish completed output from a staging directory. Turn recognised preparation and render failures into warnings so only tests that require the missing site skip. Unexpected exceptions still propagate. Collect rendered-output tests from any available subset. Skip the member-heading coverage check when none of the packages that exercise it is available.
Numbered citation conversion now takes an anchor stem, so it can namespace each object's citations. Two tests written against the earlier single-argument form no longer applied. Both behaviours they covered are asserted more thoroughly by the citation normalisation tests: prose around a citation surviving untouched, and an indented continuation joining its citation.
rich-iannone
self-requested a review
August 31, 2026 15:14
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
2 participants
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.
This PR retires the post-render docstring translators, moving docstring normalisation into the resolution hooks, where the configured parser is actually known. The configured parser now decides what counts as a docstring section, so numpy and google docstrings no longer pick up Sphinx-only handling.
One of the retired translators handled citations. Citations that use RST syntax continue to be supported along with those that resolve through a project bibliography. There are two new citation features.
[N]_references link in both directions, references render as superscript markers.Known and unresolved issues with citations: #334