Docs: one layer, one table on the API overview - #111
Merged
Conversation
The API overview rendered every module twice: once in the package docstring's three layer lists, then again in the lists the page generator appended under the same three headings. The generator now renders the package docstring alone, and the docstring gives each layer a heading, a short paragraph on what the layer is for, and a table of its modules in the order a reader meets them. A new docs gate fails when an exporting module is missing from those tables, so the overview cannot drift from the import surface. Claude-Session: https://claude.ai/code/session_01GL26QnA6dCrvUc3WmhzFSa
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.
The API overview page rendered every module twice: the package docstring listed them under three layers, then
gen_api_reference.pyappended its own three headed lists of the same modules.What changed:
src/osrlib/__init__.py: each layer is now a heading, a short paragraph on what the layer is for, and a table of its modules in the order a reader meets them. Module links use the[name][]autorefs form so every row fits the 120-character source limit.tools/docs/gen_api_reference.py: the overview page renders the package docstring alone, at heading level 1 so the layer headings land in the page's table of contents as top-level sections.tests/test_docs_gates.py: a new gate fails when an exporting module is missing from the tables, or a table names a module that no longer exports anything.Checked with
ruff format --check,ruff check,pyright src, the fullpytestrun, andmkdocs build --strict.https://claude.ai/code/session_01GL26QnA6dCrvUc3WmhzFSa