docs: Overhaul documentation with autodoc directives and per-tool pages#12
Open
tony wants to merge 4 commits intotui-toolingfrom
Open
docs: Overhaul documentation with autodoc directives and per-tool pages#12tony wants to merge 4 commits intotui-toolingfrom
tony wants to merge 4 commits intotui-toolingfrom
Conversation
Fix _MODEL_CLASSES staleness — replace hardcoded 10-model set with
dynamic discovery via _discover_model_classes() using Pydantic
introspection + __module__ filtering. PaneSnapshot and
ContentChangeResult now get correct cross-references.
Add 5 new directives: fastmcp-resource, fastmcp-resourcesummary,
fastmcp-model, fastmcp-model-fields, fastmcp-modelsummary.
Add 4 new roles: {resource}, {resourceref}, {model}, {modelref}.
Add 4 new custom nodes with blue (resource) and purple (model) badges.
Resource collection uses _ResourceCollector (mirrors _ToolCollector)
to capture URI templates, titles, and params from hierarchy.py without
executing tmux code. Model collection introspects BaseModel subclasses
via model_fields with proper default_factory handling.
Replace automodule dumps in reference/api/resources.md and models.md
with structured autodoc output. Add resource and model role demos.
Tests: 44 new tests across 3 files (251 total).
Move each of the 38 tools from 4 area pages (sessions.md, windows.md,
panes.md, options.md) into individual pages under docs/tools/.
Fix FastMCPToolSummaryDirective link generation to use anchor-only refs
instead of hardcoded area paths, making it page-layout-agnostic.
Add sphinxcontrib-rediraffe redirects for the 4 removed area pages
pointing to tools/index where the grid cards provide navigation.
Grid cards, {tool}/{toolref}/{tooliconl} roles, and all cross-references
continue working unchanged — Sphinx resolves labels globally via
StandardDomain regardless of which page contains the section.
Move tool pages from flat docs/tools/<tool>.md to hierarchy-based subdirectories: server/, session/, window/, pane/. - server/ (8): list-sessions, get-server-info, create-session, kill-server, show-option, set-option, show-environment, set-environment - session/ (5): list-windows, create-window, rename-session, select-window, kill-session - window/ (7): list-panes, split-window, rename-window, select-layout, resize-window, move-window, kill-window - pane/ (18): all pane interaction tools Update toctree paths to match new directory structure.
Monkeypatch SphinxContentsFilter to raise SkipNode for all badge node types (_safety_badge_node, _resource_badge_node, _model_badge_node). This is the same pattern Sphinx uses for visit_image in titles. Badges stay inside nodes.title for proper heading rendering, but are stripped during toctree text extraction so the sidebar shows clean tool names without badge text or emoji leakage. Add CSS to size badges at 0.5em within h1/h2 headings for medium button appearance rather than full-scale heading text.
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
Builds on #11. Overhauls the documentation system:
fastmcp-resource,fastmcp-resourcesummary,fastmcp-model,fastmcp-model-fields,fastmcp-modelsummarydirectives plus{resource},{resourceref},{model},{modelref}roles. Fix_MODEL_CLASSESstaleness (PaneSnapshot and ContentChangeResult were missing).server/,session/,window/,pane/). Grid cards on index pages serve as navigation. sphinxcontrib-rediraffe redirects for old paths.SphinxContentsFilterto raiseSkipNodefor badge nodes — same pattern Sphinx uses forvisit_image. Badges render in headings but are stripped from toctree/sidebar. CSS removescode.literalbackground in sidebar.New directives & roles
fastmcp-resource,fastmcp-resourcesummary,fastmcp-model,fastmcp-model-fields,fastmcp-modelsummary{resource},{resourceref},{model},{modelref}Page structure
Test plan
uv run ruff check . --fix --show-fixespassesuv run ruff format .— no changesuv run mypy— no issuesuv run py.test --reruns 0 -vvv— 251 tests passjust build-docs— builds clean