feat(sphinx-autodoc-fastmcp): FastMCP tool docs extension#13
Merged
Conversation
why: Reusable Sphinx extension for FastMCP tool cards, badges, directives, and cross-reference roles (extracted from libtmux-mcp local _ext). what: - New package with collector, directives (desc-based cards), roles, transforms - Unit tests under tests/ext/fastmcp/
why: Register the new package for workspace resolution, dev deps, ruff, and pytest discovery; lockfile pairs with manifest per AGENTS.md. what: - tool.uv.sources and dev dependency for sphinx-autodoc-fastmcp - ruff first-party and per-file ignores; doctest testpaths - uv.lock
why: Publish package reference in docs; legacy extensions/* redirects; CHANGES entry; doctest expectations for workspace discovery. what: - docs/packages/sphinx-autodoc-fastmcp.md and redirects.txt line - package_reference doctest set; test_package_reference expected names - CHANGES bullet for the new extension
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## main #13 +/- ##
==========================================
- Coverage 89.17% 85.14% -4.04%
==========================================
Files 78 95 +17
Lines 7576 8495 +919
==========================================
+ Hits 6756 7233 +477
- Misses 820 1262 +442 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
…PI-style/pytest why: Unified BadgeNode API for consistent badge styling across autodoc plugins; restore FastMCP tool sections and TOC sidebar compact badges. what: - Add sphinx-autodoc-badges package with BadgeNode, builders, shared CSS - Migrate sphinx-autodoc-fastmcp, api-style, pytest-fixtures to shared badges - Document new package; update redirects and package reference tests
why: Consolidate iterative CSS work into one logical change: gptheme parity for safety and MCP tool badges, TOC layout, robust colors when theme CSS loads later, and subtle inset depth on solid pills. what: - sphinx_autodoc_badges: --sab-* fallbacks, buff shadow, TOC compact badges with icons - sphinx_autodoc_fastmcp: matte palette, borders, metrics, dark theme type tool
…CSS reference why: The stub page lacked API docs, intersphinx links, badge demos, and CSS variable/class documentation that sibling package pages provide. what: - conf.py: sys.path + sphinx_autodoc_badges + sab_demo extensions - sab_demo.py: directive rendering every badge variant via real API - sphinx-autodoc-badges.md: setup/intersphinx, autodoc API, live demos, CSS custom properties, class reference, context sizing, downstream table
why: Extensions and downstream docs need explicit size control that composes with fill, style, and color classes without being overridden by context selectors. what: - CSS: sab-xs/sab-sm/sab-lg/sab-xl classes; context rules wrapped in :where() - Python: badge_size param on BadgeNode, size param on build_badge() - SAB constants: XS, SM, LG, XL - Tests for size classes, invalid size ValueError, build_badge forwarding
why: Document the new xs/sm/lg/xl size API alongside existing badge demos. what: - sab_demo.py: size variants row (xs through xl side-by-side) - sphinx-autodoc-badges.md: badge_size param, sab-xs–sab-xl in CSS table, note that explicit sizes override context selectors
…only why: BadgeNode renders <span>, not <abbr>; the abbr.gas-badge / abbr.spf-badge selectors no longer match, so border-color reinforcement was lost. what: - api_style.css: abbr.gas-* → .gas-*.gas-badge (element-agnostic) - sphinx_autodoc_pytest_fixtures.css: abbr.spf-* → .spf-*.spf-badge
…grounds why: sab-outline sets background:transparent at (0,2,0) specificity, which overrides gas-type-*/spf-* background-color at (0,1,0). Production badges are filled — the extension CSS provides the backgrounds, not sab. what: - api-style: type badges use default fill (filled); modifiers keep outline - pytest-fixtures: all badges use default fill (CSS handles backgrounds)
why: The abbr→class migration dropped text-decoration: underline dotted that was previously on abbr.gas-badge. what: - Add text-decoration: underline dotted to .gas-badge base rule
why: CI runs mypy . (whole workspace) but local ran mypy src tests; dict return annotation needs generic args to pass strict type-arg check. what: - Add import typing as t - Annotate setup() return type as dict[str, t.Any]
…e fix why: Record the badges infrastructure, size API, and rendering regression fix. what: - Features: sphinx-autodoc-badges package, xs/sm/lg/xl size variants - Bug fixes: badge colors/borders/underline after BadgeNode migration - Workspace packages: sphinx-autodoc-badges entry
…ection why: Undocumented autodoc objects left empty desc_content, producing blank <dd> rows and extra vertical space in API cards. what: - Add _prune_empty_desc_content with doctest - Invoke it from on_doctree_resolved for handled py desc nodes - Add unit tests for direct prune, nonempty preserve, and pipeline
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
Adds
sphinx-autodoc-fastmcp: a Sphinx extension for documenting FastMCP tools with card-styledesclayouts (aligned withsphinx-autodoc-api-style), safety badges, MyST directives (fastmcp-tool,fastmcp-tool-input,fastmcp-toolsummary), and roles (:tool:,:toolref:,:badge:, etc.).Commits (per AGENTS.md)
tests/ext/fastmcp/pyproject.toml+uv.lockonlyChecklist
uv run pytestuv run ruff check