Fix docs site theme, highlighting, and cross-references#19
Merged
Conversation
Enable the light/dark palette toggle and Pygments syntax highlighting (pymdownx.highlight/superfences/inlinehilite) in the mkdocs-material site. Fix Examples blocks rendering their code fences as literal text: griffe's Google parser stops recognizing a section when a blank line separates the header from its content, so every `Examples:` block leaked its ```python fence. Remove the blank line in all 11 affected docstrings and drop the ruff `ignore = ["D412"]` exception that had been suppressing the one rule (D412) that catches exactly this — it now guards against regressions. Add remote inventories (pydantic, Python stdlib) so cross-references to external symbols resolve to upstream docs instead of dangling, and add `watch: [src]` so `mkdocs serve` live-reloads on docstring edits.
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.
Summary
Documentation site fixes for the mkdocs-material build.
paletteblock withdefault/slateschemes and a header toggle that respectsprefers-color-schemeand remembers the reader's choice.pymdownx.highlight+superfences+inlinehilite. superfences coexists with the existing--8<--snippet markers.Examples:blocks rendered as literal text (the main bug) — griffe's Google docstring parser stops recognizing a section when a blank line separates the header from its content, so everyExamples:block leaked its```pythonfence into the page as an indented code block. Removed the blank line in all 11 affected docstrings.ignore = ["D412"]had been suppressing "No blank lines allowed between a section header and its content" — the exact rule that catches this. It's now active (and passing), so regressions are caught at lint time.objects.invso cross-references to external symbols (e.g.BaseModel,Field,Enum,ValueError) link to upstream docs instead of dangling.watch: [src]—mkdocs servewatchesdocs/andmkdocs.ymlby default, not the package source; without this, docstring edits didn't live-reload and the preview went stale.Test plan
uv run ruff check src— passes (D412 now enforced)uv run ruff format --check src— cleanuv run mkdocs build --strict— builds clean; 0 pages leak literal```pythonfences (was 10); external symbols link to pydantic/python docs across the referenceNote: the strict build fetches the remote inventories, so CI needs network access (already required for the fetch to succeed).