Skip to content

docs: Overhaul documentation with autodoc directives and per-tool pages#12

Open
tony wants to merge 6 commits intomainfrom
docs-overhaul-april-early-2026
Open

docs: Overhaul documentation with autodoc directives and per-tool pages#12
tony wants to merge 6 commits intomainfrom
docs-overhaul-april-early-2026

Conversation

@tony
Copy link
Copy Markdown
Member

@tony tony commented Apr 9, 2026

Summary

Builds on #11. Overhauls the documentation system:

  • Resource & model autodoc directives: Add fastmcp-resource, fastmcp-resourcesummary, fastmcp-model, fastmcp-model-fields, fastmcp-modelsummary directives plus {resource}, {resourceref}, {model}, {modelref} roles. Fix _MODEL_CLASSES staleness (PaneSnapshot and ContentChangeResult were missing).
  • Per-tool pages: Split 38 tools from 4 area pages into individual files organized by tmux hierarchy (server/, session/, window/, pane/). Grid cards on index pages serve as navigation. sphinxcontrib-rediraffe redirects for old paths.
  • Sidebar badge fix: Monkeypatch SphinxContentsFilter to raise SkipNode for badge nodes — same pattern Sphinx uses for visit_image. Badges render in headings but are stripped from toctree/sidebar. CSS removes code.literal background in sidebar.

New directives & roles

Type Count Items
Directives +5 fastmcp-resource, fastmcp-resourcesummary, fastmcp-model, fastmcp-model-fields, fastmcp-modelsummary
Roles +4 {resource}, {resourceref}, {model}, {modelref}
Custom nodes +4 resource badge, model badge, resource ref, model ref
Tests +44 resource collection, model collection, badge nodes, roles

Page structure

docs/tools/
├── index.md          (grid cards for all 38 tools)
├── server/index.md   (8 tools)
├── session/index.md  (5 tools)
├── window/index.md   (7 tools)
└── pane/index.md     (18 tools)

Test plan

  • uv run ruff check . --fix --show-fixes passes
  • uv run ruff format . — no changes
  • uv run mypy — no issues
  • uv run py.test --reruns 0 -vvv — 251 tests pass
  • just build-docs — builds clean
  • Sidebar verified via Playwright: no badges, no emoji leakage, no code background

tony added 6 commits April 8, 2026 17:24
@tony
feat(tools): Add 11 new MCP tools for agent workflows
1a1e659 
New pane tools: snapshot_pane (rich capture with cursor/mode/scroll
metadata), wait_for_content_change (detect any screen change),
select_pane (directional navigation), swap_pane, pipe_pane,
display_message (tmux format string queries), enter_copy_mode,
exit_copy_mode, paste_text (bracketed paste via tmux buffers).

New session tool: select_window (navigate by ID/index/direction).

New window tool: move_window (reorder or cross-session moves).

Models: PaneSnapshot, ContentChangeResult.
Tests: 22 new tests covering all new tools.
@tony
docs(tools): Add documentation for all 11 new tools
f5de77a 
Document snapshot_pane, wait_for_content_change, display_message,
select_pane, select_window, swap_pane, move_window, pipe_pane,
enter_copy_mode, exit_copy_mode, and paste_text with usage guidance,
JSON examples, and parameter tables following existing patterns.

Update tools/index.md with new grid cards and expanded "Which tool
do I want?" decision guide covering navigation, layout, scrollback,
and paste workflows.
@tony
feat(docs): Add resource and model autodoc directives
f0ee3d0 
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).
@tony
docs(tools): Split tools into individual pages with grid navigation
c097c53 
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.
@tony
docs(tools): Organize tool pages by tmux hierarchy
84c2cfd 
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.
@tony
docs(style): Strip badges from sidebar via SphinxContentsFilter
c729553 
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.
Base automatically changed from tui-tooling to main April 13, 2026 01:24
tony added a commit that referenced this pull request Apr 15, 2026
@tony
mcp(refactor[_utils,tools]): hoist _tmux_argv; add paste_text timeout…
a53b86f 
… + libtmux_mcp_ prefix

why: Three sibling modules had each rolled their own tmux argv
     builder:

     * buffer_tools.py defined ``_tmux_argv`` inline.
     * wait_for_tools.py defined an identical ``_tmux_argv`` inline
       (docstrings differed; bodies were byte-for-byte identical).
     * pane_tools/io.py::paste_text rebuilt the same socket-aware
       argv by hand.

     Two code-review findings converged on this file set:

     * Important #4 (Loom review): paste_text called ``subprocess.run``
       with no ``timeout=`` at all, so a hung tmux could block the
       tool call indefinitely. Adjacent sibling buffer tools had the
       timeout but paste_text did not.
     * Suggestion #11/#12: the duplicate helpers and the parallel
       inline build in paste_text are one refactor, not three.

     Also: paste_text's internal ``mcp_paste_<uuid>`` buffer name did
     not share the ``libtmux_mcp_`` namespace the new buffer_tools
     module established, so an operator auditing MCP-owned buffers
     via ``list-buffers | grep libtmux_mcp_`` would miss
     paste-through buffers.

what:
- Hoist ``_tmux_argv`` into src/libtmux_mcp/_utils.py as an internal
  helper with a NumPy-style docstring + two doctests (socket_name
  only; socket_path only). Honours ``server.tmux_bin`` if set.
- Delete the inline ``_tmux_argv`` definitions in
  src/libtmux_mcp/tools/buffer_tools.py and
  src/libtmux_mcp/tools/wait_for_tools.py; import the shared helper.
  The now-unused ``Server`` TYPE_CHECKING import is also dropped.
- Update src/libtmux_mcp/tools/pane_tools/io.py::paste_text:
  * Replace the inline argv construction with ``_tmux_argv(server,
    "load-buffer", "-b", buffer_name, tmppath)``.
  * Add ``timeout=5.0`` on the ``subprocess.run`` call, matching the
    sibling buffer tools.
  * Add an explicit ``except subprocess.TimeoutExpired`` branch with
    the same shape buffer_tools landed in the previous commit.
  * Rename the buffer prefix from ``mcp_paste_<uuid>`` to
    ``libtmux_mcp_paste_<uuid>``.
- Update tests/test_pane_tools.py::test_paste_text_does_not_leak_named_buffer
  to assert the new prefix (and updates the docstring rationale).
- Add tests/test_utils.py::test_tmux_argv_honours_socket_and_binary
  parametrized over four cases: socket_name only, socket_path only,
  both set, and explicit tmux_bin override.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@tony