Skip to content

Repository navigation

Commit 48ea0fe

Browse files
tonytony
committed
docs(redesign): restructure documentation to Library Skeleton pattern
why: The landing page mixed README include with custom content. Topic files (architecture, concepts, safety) were scattered at root. No topics/ or project/ sections. The tools overview missed the "Server Management" category. A broken {ref} link pointed to a nonexistent "about" page. what: Landing page: - Compose standalone homepage with hero + pre-alpha warning - "Get started in one command" block above grid cards for instant activation (claude mcp add + agent prompt example) - Two responsive 3-card grid rows: Quickstart/Tools/Configuration + MCP Clients/Topics/Contributing - Install snippet (uvx + pip) Structure: - Create topics/ — move architecture.md, concepts.md, safety.md, troubleshooting.md (from guides/) into it with grid cards index - Create project/ section with grid cards: contributing.md (moved from development.md), code-style.md, releasing.md - Add grid cards to topics/, reference/api/, tools/ index pages - Add "Server Management" card to tools/index.md (was missing) - Fix broken {ref}`about <about>` → explicit API reference link Dependencies: - Add sphinx-design to docs and dev dependency groups - Add sphinx_design extension and myst_heading_anchors = 4 to conf.py Redirects: - architecture.md → topics/architecture.md - concepts.md → topics/concepts.md - safety.md → topics/safety.md - guides/troubleshooting.md → topics/troubleshooting.md - development.md → project/contributing.md - Removed stale circular redirect (topics/safety → safety)
1 parent d54e4e9 commit 48ea0fe

14 files changed

Lines changed: 293 additions & 42 deletions

File tree

‎docs/conf.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,10 +40,13 @@
4040
"sphinx_copybutton",
4141
"sphinxext.opengraph",
4242
"sphinxext.rediraffe",
43+
"sphinx_design",
4344
"myst_parser",
4445
"linkify_issues",
4546
]
4647

48+
myst_heading_anchors = 4
49+
4750
myst_enable_extensions = [
4851
"colon_fence",
4952
"substitution",

‎docs/index.md‎

Lines changed: 67 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -8,56 +8,88 @@ MCP server for tmux, powered by [libtmux](https://libtmux.git-pull.com/).
88
**Pre-alpha.** APIs may change. [Feedback welcome](https://github.com/tmux-python/libtmux-mcp/issues).
99
```
1010

11-
```{include} ../README.md
12-
:start-after: "## Quick start"
13-
:end-before: "## What's included"
11+
## Get started in one command
12+
13+
```console
14+
$ claude mcp add libtmux -- uvx libtmux-mcp
1415
```
1516

16-
```{toctree}
17-
:caption: Getting Started
18-
:maxdepth: 2
19-
:hidden:
17+
Then ask your agent:
2018

21-
installation
22-
quickstart
23-
clients
24-
concepts
25-
configuration
26-
safety
19+
```
20+
> List all tmux sessions and show the panes in the first one.
2721
```
2822

29-
```{toctree}
30-
:caption: Tools
31-
:maxdepth: 2
32-
:hidden:
23+
::::{grid} 1 2 3 3
24+
:gutter: 2 2 3 3
3325

34-
tools/index
35-
```
26+
:::{grid-item-card} Quickstart
27+
:link: quickstart
28+
:link-type: doc
29+
Zero to a working tool invocation in 5 minutes.
30+
:::
3631

37-
```{toctree}
38-
:caption: Guides
39-
:maxdepth: 2
40-
:hidden:
32+
:::{grid-item-card} Tools
33+
:link: tools/index
34+
:link-type: doc
35+
30+ tools for sessions, windows, panes, capture, and more.
36+
:::
37+
38+
:::{grid-item-card} Configuration
39+
:link: configuration
40+
:link-type: doc
41+
Environment variables, safety tiers, socket selection.
42+
:::
43+
44+
::::
45+
46+
::::{grid} 1 2 3 3
47+
:gutter: 2 2 3 3
48+
49+
:::{grid-item-card} MCP Clients
50+
:link: clients
51+
:link-type: doc
52+
Copy-pasteable config for Claude Code, Cursor, VS Code, and more.
53+
:::
4154

42-
guides/troubleshooting
55+
:::{grid-item-card} Topics
56+
:link: topics/index
57+
:link-type: doc
58+
Architecture, concepts, safety tiers, troubleshooting.
59+
:::
60+
61+
:::{grid-item-card} Contributing
62+
:link: project/index
63+
:link-type: doc
64+
Development setup, code style, release process.
65+
:::
66+
67+
::::
68+
69+
## Install
70+
71+
```console
72+
$ uvx libtmux-mcp
4373
```
4474

75+
```console
76+
$ pip install libtmux-mcp
77+
```
78+
79+
See [Installation](installation.md) for all methods and options.
80+
4581
```{toctree}
46-
:caption: Reference
47-
:maxdepth: 2
4882
:hidden:
4983
84+
installation
85+
quickstart
86+
clients
87+
configuration
88+
tools/index
89+
topics/index
5090
reference/api/index
5191
reference/compatibility
92+
project/index
5293
history
53-
```
54-
55-
```{toctree}
56-
:caption: Project
57-
:hidden:
58-
59-
architecture
60-
development
6194
glossary
62-
GitHub <https://github.com/tmux-python/libtmux-mcp>
6395
```

‎docs/project/code-style.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
(code-style)=
2+
3+
# Code style
4+
5+
## Linting and formatting
6+
7+
libtmux-mcp uses [ruff](https://docs.astral.sh/ruff/) for linting and formatting:
8+
9+
```console
10+
$ uv run ruff check .
11+
```
12+
13+
```console
14+
$ uv run ruff format .
15+
```
16+
17+
## Type checking
18+
19+
[mypy](https://mypy-lang.org/) with strict mode:
20+
21+
```console
22+
$ uv run mypy
23+
```
24+
25+
## Docstrings
26+
27+
NumPy-style docstrings throughout.
28+
29+
## Imports
30+
31+
- `from __future__ import annotations` at the top of every file.
32+
- `import typing as t` and access via namespace.
33+
- Standard-library modules imported by namespace (`import pathlib`, not `from pathlib import Path`).

docs/development.md renamed to docs/project/contributing.md

File renamed without changes.

‎docs/project/index.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
(project)=
2+
3+
# Project
4+
5+
Information for contributors and maintainers.
6+
7+
::::{grid} 1 1 2 2
8+
:gutter: 2 2 3 3
9+
10+
:::{grid-item-card} Contributing
11+
:link: contributing
12+
:link-type: doc
13+
Development setup, running tests, submitting PRs.
14+
:::
15+
16+
:::{grid-item-card} Code Style
17+
:link: code-style
18+
:link-type: doc
19+
Ruff, mypy, NumPy docstrings, import conventions.
20+
:::
21+
22+
:::{grid-item-card} Releasing
23+
:link: releasing
24+
:link-type: doc
25+
Release checklist and version policy.
26+
:::
27+
28+
::::
29+
30+
```{toctree}
31+
:hidden:
32+
33+
contributing
34+
code-style
35+
releasing
36+
```

‎docs/project/releasing.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
(releasing)=
2+
3+
# Releasing
4+
5+
## Version scheme
6+
7+
libtmux-mcp follows [PEP 440](https://peps.python.org/pep-0440/) with alpha suffixes during pre-1.0 development (e.g. `0.1.0a0`).
8+
9+
## Release checklist
10+
11+
1. Update `CHANGES`.
12+
2. Bump version in `src/libtmux_mcp/__about__.py`.
13+
3. Commit and tag: `git tag v0.X.Y`.
14+
4. Push with tags: `git push --follow-tags`.
15+
5. CI publishes to PyPI.

‎docs/redirects.txt‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,14 @@
1-
"about" "concepts"
2-
"topics/safety" "safety"
3-
"developing" "development"
1+
"about" "topics/concepts"
2+
"developing" "project/contributing"
3+
"development" "project/contributing"
44
"api/index" "reference/api/index"
55
"api/server" "reference/api/server"
66
"api/tools" "reference/api/tools"
77
"api/models" "reference/api/models"
88
"api/middleware" "reference/api/middleware"
99
"api/resources" "reference/api/resources"
1010
"api/utils" "reference/api/utils"
11+
"architecture" "topics/architecture"
12+
"concepts" "topics/concepts"
13+
"safety" "topics/safety"
14+
"guides/troubleshooting" "topics/troubleshooting"

‎docs/reference/api/index.md‎

Lines changed: 42 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,49 @@
22

33
# API Reference
44

5+
::::{grid} 1 1 2 2
6+
:gutter: 2 2 3 3
7+
8+
:::{grid-item-card} Server
9+
:link: server
10+
:link-type: doc
11+
MCP server entry point and lifecycle.
12+
:::
13+
14+
:::{grid-item-card} Tools
15+
:link: tools
16+
:link-type: doc
17+
Tool function implementations.
18+
:::
19+
20+
:::{grid-item-card} Models
21+
:link: models
22+
:link-type: doc
23+
Pydantic models for requests and responses.
24+
:::
25+
26+
:::{grid-item-card} Middleware
27+
:link: middleware
28+
:link-type: doc
29+
Safety-tier enforcement and request hooks.
30+
:::
31+
32+
:::{grid-item-card} Resources
33+
:link: resources
34+
:link-type: doc
35+
MCP resource providers.
36+
:::
37+
38+
:::{grid-item-card} Utils
39+
:link: utils
40+
:link-type: doc
41+
Shared helpers and utilities.
42+
:::
43+
44+
::::
45+
546
```{toctree}
6-
:maxdepth: 2
47+
:hidden:
748
849
server
950
tools

‎docs/tools/index.md‎

Lines changed: 49 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,53 @@
44

55
All tools accept an optional `socket_name` parameter for multi-server support. It defaults to the `LIBTMUX_SOCKET` env var. See {ref}`configuration`.
66

7+
::::{grid} 1 1 2 2
8+
:gutter: 2 2 3 3
9+
10+
:::{grid-item-card} Discovery
11+
Find and inspect tmux objects.
12+
^^^
13+
`list_sessions` `list_windows` `list_panes` `get_server_info` `get_pane_info`
14+
:::
15+
16+
:::{grid-item-card} Capture & Search
17+
Read and search terminal output.
18+
^^^
19+
`capture_pane` `search_panes` `wait_for_text`
20+
:::
21+
22+
:::{grid-item-card} Session Lifecycle
23+
Create and manage sessions.
24+
^^^
25+
`create_session` `rename_session` `kill_session`
26+
:::
27+
28+
:::{grid-item-card} Windows & Panes
29+
Create, split, and organize.
30+
^^^
31+
`create_window` `split_window` `rename_window` `select_layout` `resize_window` `resize_pane` `kill_window` `kill_pane`
32+
:::
33+
34+
:::{grid-item-card} Execution
35+
Send commands and interact with terminals.
36+
^^^
37+
`send_keys` `set_pane_title` `clear_pane`
38+
:::
39+
40+
:::{grid-item-card} Options & Environment
41+
Read and set tmux configuration.
42+
^^^
43+
`show_option` `set_option` `show_environment` `set_environment`
44+
:::
45+
46+
:::{grid-item-card} Server Management
47+
Destructive server operations.
48+
^^^
49+
`kill_server`
50+
:::
51+
52+
::::
53+
754
## Discovery
855

956
Find and inspect tmux objects.
@@ -66,6 +113,5 @@ Read and set tmux configuration.
66113

67114
## Tool parameter reference
68115

69-
For full parameter documentation (types, defaults, descriptions), see the {ref}`about <about>` page.
70-
71-
For API-level documentation, see the {ref}`API reference <api>`.
116+
For full parameter documentation (types, defaults, descriptions), see the
117+
[API reference](../reference/api/index.md).

docs/architecture.md renamed to docs/topics/architecture.md

File renamed without changes.

0 commit comments

Comments
 (0)