Docs overhaul: contract docstrings + rebuilt quickstart/tutorials/troubleshooting - #2
Merged
Conversation
…ubleshooting
Render fix (package-wide): Google docstring example sections used the singular
"Example:" keyword, which griffe does not recognise as a code section — every
example rendered as nested blockquotes and tripped mkdocs-autorefs ("Could not
find cross-reference target") on bracketed subscripts like g["cat"]["sat"].
Renaming to "Examples:" makes them render as highlighted code blocks and clears
all three strict-mode warnings.
Docs:
- Enable mkdocs strict mode; add markdown_extensions (admonition, pymdownx
highlight/superfences/snippets) for a richer site and to embed example scripts.
- Rewrite quickstart as a runnable, end-to-end walkthrough (verified in a venv).
- New tutorial: word-association graphs + concept-to-concept pathfinding via
networkx (no new public API), with a conceptual note on human-norm comparison.
- New troubleshooting page from the real failure modes (spaCy model, Python.h /
Cython headers, pickle safety, stopword ValueErrors, empty graphs, NodeNotFound).
- Convert example pages from link stubs to embedded source (snippets) + real output.
- Add missing API page for get_stopwords; complete the reference.
- Promote the load_graph pickle-safety caveat to a prominent Warning admonition.
- gitignore the mkdocs site/ build output.
make ci green; mkdocs build --strict warning-free.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This was referenced Jun 29, 2026
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
Phase 1 of the docs/design/test hardening pass — documentation only. The biggest single win is a package-wide rendering fix; the rest rebuilds the readthedocs prose so it actually runs.
Render fix (the root cause behind the "thin/broken docs")
Every Google-style example used the singular
Example:keyword. griffe only treats the pluralExamples:as a code section, so all examples rendered as ugly nested blockquotes, and mkdocs-autorefs misread bracketed doctest subscripts (g["cat"]["sat"]) as cross-reference links — the three warnings that blocked strict mode. Renaming toExamples:makes them render as highlighted code blocks and clears strict mode.Docs
strict: true) +markdown_extensions(admonitions, pymdownx highlight/superfences/snippets).nx.Graph, so no new public API). Includes a conceptual note on comparing against human norms (Nelson / SWOW), deferred toCHANGES_SUMMARY.md.Python.h/Cython headers, pickle safety, stopwordValueErrors, empty graphs,NodeNotFound).get_stopwordspage.load_graphpickle-safety caveat to a prominentWarningadmonition.gitignorethe mkdocssite/build output.Source changes
Docstring-only:
Example:→Examples:across all modules, plus theload_graphwarning. No behaviour changes.Verification
make cigreen (format + lint + typecheck + 118 tests pass, 94% coverage).mkdocs build --strictwarning-free.Notes
uv.lockhas a pre-existing 0.1.0→0.1.1 drift unrelated to this PR; intentionally left untouched.🤖 Generated with Claude Code