docs(feat[api-style]): Visual improvements to API docs via gp-sphinx#10
Merged
docs(feat[api-style]): Visual improvements to API docs via gp-sphinx#10
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #10 +/- ##
==========================================
+ Coverage 71.10% 79.71% +8.61%
==========================================
Files 20 17 -3
Lines 1419 779 -640
Branches 186 93 -93
==========================================
- Hits 1009 621 -388
+ Misses 365 121 -244
+ Partials 45 37 -8 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
…i-style why: Add type and modifier badges to autodoc entries. what: - Add sphinx_autodoc_api_style to extra_extensions in docs/conf.py
…to 0.0.1a5 why: Align docs dependencies with latest gp-sphinx workspace releases. what: - Pin sphinx-autodoc-api-style and bump gp-sphinx packages to 0.0.1a5 - Regenerate uv.lock
…rces why: Consume the new extension from gp-sphinx; optional path overrides for a sibling gp-sphinx clone during development. what: - dev/docs dependency on sphinx-autodoc-fastmcp - tool.uv.sources for gp-sphinx, sphinx-autodoc-api-style, sphinx-autodoc-fastmcp - mypy override for sphinx_autodoc_fastmcp - uv.lock
why: Drop the inlined fastmcp_autodoc extension in favor of the gp-sphinx package; configure tool modules, area map, and section badges. what: - extra_extensions and fastmcp_* settings in docs/conf.py - remove docs/_ext/fastmcp_autodoc.py; drop _ext from sys.path
why: Lockfile reflects transitive editable deps from gp-sphinx packages. what: - uv.lock updates for sphinx-autodoc-api-style and sphinx-autodoc-fastmcp requires-dist
why: Pydantic's BaseModel uses Markdown-style [text][ref] cross-refs in docstrings, but autodoc processes them as RST, yielding citation-ref rendering instead of hyperlinks. what: - autodoc-process-docstring hook rewrites [`Name`][pkg.Name] to :any: roles - pyproject.toml: add fastmcp_autodoc to mypy ignore_missing_imports
why: Align dev docs dependencies with gp-sphinx 0.0.1a6 on PyPI. what: - Bump gp-sphinx ecosystem pins in pyproject.toml - Regenerate uv.lock
why: Pick up the sphinx-argparse-neo multi-page duplicate-label scoping fix landed in gp-sphinx PR #16, and finish the migration away from the in-tree docs/_ext/fastmcp_autodoc extension that moved to the gp-sphinx sphinx-autodoc-fastmcp package. The [tool.uv.sources] block pinned gp-sphinx / sphinx-autodoc-api-style / sphinx-autodoc-fastmcp at ../gp-sphinx/packages/*, which only resolves in the local dev workspace — CI has been failing at the uv sync step continuously since the block was introduced. Alongside that block, docs(conf): Use sphinx_autodoc_fastmcp and remove local _ext deleted docs/_ext/fastmcp_autodoc.py but left the tests/docs/_ext harness pointing at it, so once CI could actually install deps it would fail again at pytest collection on ImportError: fastmcp_autodoc. what: - Drop the [tool.uv.sources] block so all three packages resolve from PyPI in every environment - Bump gp-sphinx and sibling package pins from 0.0.1a6 to 0.0.1a7 - Remove the orphaned tests/docs/_ext/ harness (test_fastmcp_autodoc, conftest that added the removed docs/_ext to sys.path, and the tests/docs package markers); equivalent coverage now lives in gp-sphinx's sphinx-autodoc-fastmcp test suite - Drop the dead fastmcp_autodoc and tests.docs.* entries from the mypy overrides table - Regenerate uv.lock
why: Capture the api-styling migration to the gp-sphinx package stack in the unreleased notes. what: - Add a Documentation bullet under libtmux-mcp 0.1.x linking to the project PR
tony
changed the title
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.
Summary
Adopt the gp-sphinx Sphinx package stack for libtmux-mcp's API documentation. The net visual effect is card-style autodoc signatures with safety and scope badges, MyST cross-reference roles for Python objects, scoped section names in multi-page CLI docs, and polished IBM Plex typography — all landing together from the
gp-sphinx 0.0.1a7pre-release.What's new
sphinx-autodoc-api-style— card layouts, badges, MyST roles for Python objectssphinx-autodoc-badges— consistent XS/SM/LG/XL size variants with WCAG-AA contrastsphinx-argparse-neo— CLI doc builds no longer emitduplicate labelwarnings (gp-sphinx#16)sphinx-fonts— IBM Plex Sans and Mono at full weight range, zero-CLS loadingsphinx-autodoc-fastmcp— card-styledesclayouts for FastMCP tools, safety badges, MyST directivesVerification
uv run ruff check . --fix --show-fixesuv run ruff format .uv run mypyuv run py.test --reruns 0 -vvvjust build-docsAll pass on the branch tip. See gp-sphinx 0.0.1 release notes for the full list of changes covering
0.0.1a1..0.0.1a7.