docs: trim README density, add mkdocstrings API page#88
Merged
Conversation
…meta The README was never touched by the docs-trim PR (#85), so it still carried the positioning + caveat-tax prose: tighten the quickstart, repeats, and re-run blockquote; un-nest the parenthetical pileups; cut the table-restating blockquote. Wire up mkdocstrings for the importable Python API: a new pure-markdown api.md rendered from the source docstrings (sphinx style), replacing ~60 lines of hand-maintained signature/param lists in reference.md that could drift. Kept as a standalone page (not inline in the reference notebook, where ::: wouldn't be processed) — this also keeps the API reference out of the executed surface. Drop the meta-commentary explaining how the docs are built ("rendered live from --help", "curated here", "can't drift"), including the internal "unlike pytest-benchmark" rationale in the MemoryResult docstring now that mkdocstrings surfaces it to users. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Documentation build overview
9 files changed ·
|
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.
Why
Follow-up to the docs-density discussion. PR #85 trimmed the docs pages but never touched the README, which still carried the bulk of the positioning + caveat-tax prose. This also moves the importable Python API onto an auto-generated page so the hand-maintained signature lists can't drift.
What
--fail-on/"where it sits"; cut the blockquote that just restated the comparison table. (199 → 187 lines, but the win is prose weight, not count.)docs/api.mdrendered from source docstrings (docstring_style: sphinx), replacing ~60 lines of hand-listed signatures/params inreference.md. Standalone page rather than inline in the reference notebook, because:::directives aren't processed by nbconvert — this also keeps the API reference out of the executed (notebook) surface.--help", "curated here", "can't drift" asides, plus the internal "unlike pytest-benchmark…" rationale in theMemoryResultdocstring now that mkdocstrings surfaces it to users.Verification
Built
api.mdin isolation via mkdocstrings: 0 literal:::leaks, every symbol rendered, docstring prose present.uv.lockintentionally omitted.🤖 Generated with Claude Code