Skip to content

Commit 07c0ff9

Browse files
tonytony
committed
docs(redesign): restructure documentation to CLI Frontend Skeleton pattern
why: The documentation mixed user-facing CLI docs with internal Python API reference at the same sidebar level, the landing page dumped the entire README (12 H1 headings), and contributor docs were scattered. This restructure follows the Python Documentation Skeletons spec where cli/ is the primary reference surface for a CLI package and the Python API is explicitly internal. what: Structure: - Move entire docs/api/ to docs/internals/api/ (Python API is internal for a CLI package) - Rename inner api/internals/ to api/_internal/ to avoid path stutter - Create topics/ directory with workflows, troubleshooting, library-vs-cli, and plugins (moved from plugins/) - Create project/ directory (contributing, code-style, releasing) - Move developing.md to project/contributing.md - Fold about.md (stale 2016 content) into topics/index.md as a brief tmuxinator/teamocil comparison note - Delete about.md New pages: - cli/exit-codes.md — exit codes for scripting and automation - cli/recipes.md — copy-pasteable command invocations - internals/index.md — explicit "not for end users" warning - internals/architecture.md — CLI dispatch flow diagram - topics/workflows.md — CI integration, scripting patterns - topics/troubleshooting.md — common shell/PATH/tmux issues - topics/library-vs-cli.md — when to use tmuxp CLI vs libtmux, concept mapping table, what the CLI can't express - project/code-style.md — ruff, mypy, NumPy docstrings - project/releasing.md — git tags, OIDC trusted publishing Landing page: - Compose standalone homepage (no README.md includes) - One-sentence intro, 3+2 grid cards, 3-command install, inline YAML example + tmuxp load command, demo GIF Section indexes: - cli/index.md: heading "CLI Reference", 2x3 card grid for key commands + exit-codes and recipes - topics/index.md: 2x2 card grid with comparison note - project/index.md: 2x2 card grid for contributor pages (3 items) - configuration/index.md: 1x3 card grid for reference subpages Navigation: - Sidebar primary: Quickstart, CLI Reference, Workspace files, Topics, Internals, Project, Changelog - Sidebar "More" caption: The Tao of tmux, Migration, Glossary - 35 redirects for all moved files (every individual api/ file covered) - README.md URLs updated to new doc structure paths, http → https Dependencies: - Add sphinx-design to docs and dev dependency groups - Annotate all doc dependencies with documentation site URLs conf.py: - Add sphinx_design extension - Add myst_heading_anchors = 4
1 parent 3869c11 commit 07c0ff9

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

52 files changed

+674
-135
lines changed

‎README.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -132,9 +132,9 @@ Name a session:
132132
tmuxp load -s session_name ./mysession.yaml
133133
```
134134

135-
[simple](http://tmuxp.git-pull.com/examples.html#short-hand-inline) and
135+
[simple](https://tmuxp.git-pull.com/configuration/examples.html#short-hand-inline-style) and
136136
[very
137-
elaborate](http://tmuxp.git-pull.com/examples.html#super-advanced-dev-environment)
137+
elaborate](https://tmuxp.git-pull.com/configuration/examples.html#super-advanced-dev-environment)
138138
config examples
139139

140140
# User-level configurations
@@ -204,7 +204,7 @@ the CLI docs.
204204

205205
Run custom startup scripts (such as installing project dependencies)
206206
before loading tmux. See the
207-
[before_script](http://tmuxp.git-pull.com/examples.html#bootstrap-project-before-launch)
207+
[before_script](https://tmuxp.git-pull.com/configuration/examples.html#bootstrap-project-before-launch)
208208
example
209209

210210
# Load in detached state
@@ -247,7 +247,7 @@ $ tmuxp convert --yes filename
247247
# Plugin System
248248

249249
tmuxp has a plugin system to allow for custom behavior. See more about
250-
the [Plugin System](http://tmuxp.git-pull.com/plugin_system.html).
250+
the [Plugin System](https://tmuxp.git-pull.com/topics/plugins.html).
251251

252252
# Debugging Helpers
253253

@@ -272,13 +272,13 @@ environment:
272272

273273
# Docs / Reading material
274274

275-
See the [Quickstart](http://tmuxp.git-pull.com/quickstart.html).
275+
See the [Quickstart](https://tmuxp.git-pull.com/quickstart.html).
276276

277-
[Documentation](http://tmuxp.git-pull.com) homepage (also in
277+
[Documentation](https://tmuxp.git-pull.com) homepage (also in
278278
[中文](http://tmuxp-zh.rtfd.org/))
279279

280280
Want to learn more about tmux itself? [Read The Tao of Tmux
281-
online](http://tmuxp.git-pull.com/about_tmux.html).
281+
online](https://tmuxp.git-pull.com/about_tmux.html).
282282

283283
# Donations
284284

@@ -295,7 +295,7 @@ See donation options at <https://tony.sh/support.html>.
295295
- python support: >= 3.10, pypy, pypy3
296296
- Source: <https://github.com/tmux-python/tmuxp>
297297
- Docs: <https://tmuxp.git-pull.com>
298-
- API: <https://tmuxp.git-pull.com/api.html>
298+
- API: <https://tmuxp.git-pull.com/internals/api/index.html>
299299
- Changelog: <https://tmuxp.git-pull.com/history.html>
300300
- Issues: <https://github.com/tmux-python/tmuxp/issues>
301301
- Test Coverage: <https://codecov.io/gh/tmux-python/tmuxp>

‎docs/about.md‎

Lines changed: 0 additions & 104 deletions
This file was deleted.

‎docs/cli/exit-codes.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
(cli-exit-codes)=
2+
3+
# Exit Codes
4+
5+
tmuxp uses standard exit codes for scripting and automation.
6+
7+
| Code | Meaning |
8+
|------|---------|
9+
| `0` | Success |
10+
| `1` | General error (config validation, tmux command failure) |
11+
| `2` | Usage error (invalid arguments, missing required options) |
12+
13+
## Usage in Scripts
14+
15+
```bash
16+
#!/bin/bash
17+
tmuxp load my-workspace.yaml
18+
if [ $? -ne 0 ]; then
19+
echo "Failed to load workspace"
20+
exit 1
21+
fi
22+
```
23+
24+
```bash
25+
#!/bin/bash
26+
tmuxp load -d my-workspace.yaml || {
27+
echo "tmuxp failed with exit code $?"
28+
exit 1
29+
}
30+
```

‎docs/cli/index.md‎

Lines changed: 50 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,48 @@
22

33
(commands)=
44

5-
# Commands
5+
# CLI Reference
6+
7+
::::{grid} 2
8+
:gutter: 3
9+
10+
:::{grid-item-card} tmuxp load
11+
:link: load
12+
:link-type: doc
13+
Load tmux sessions from workspace configs.
14+
:::
15+
16+
:::{grid-item-card} tmuxp shell
17+
:link: shell
18+
:link-type: doc
19+
Interactive Python shell with tmux context.
20+
:::
21+
22+
:::{grid-item-card} tmuxp freeze
23+
:link: freeze
24+
:link-type: doc
25+
Export running sessions to config files.
26+
:::
27+
28+
:::{grid-item-card} tmuxp convert
29+
:link: convert
30+
:link-type: doc
31+
Convert between YAML and JSON formats.
32+
:::
33+
34+
:::{grid-item-card} Exit Codes
35+
:link: exit-codes
36+
:link-type: doc
37+
Exit codes for scripting and automation.
38+
:::
39+
40+
:::{grid-item-card} Recipes
41+
:link: recipes
42+
:link-type: doc
43+
Copy-pasteable command invocations.
44+
:::
45+
46+
::::
647

748
```{toctree}
849
:caption: General commands
@@ -38,6 +79,14 @@ debug-info
3879
completion
3980
```
4081

82+
```{toctree}
83+
:caption: Reference
84+
:maxdepth: 1
85+
86+
exit-codes
87+
recipes
88+
```
89+
4190
(cli-main)=
4291

4392
(tmuxp-main)=

‎docs/cli/recipes.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
(cli-recipes)=
2+
3+
# Recipes
4+
5+
Copy-pasteable command invocations for common tasks.
6+
7+
## Load a workspace
8+
9+
```console
10+
$ tmuxp load my-workspace.yaml
11+
```
12+
13+
## Load in detached mode
14+
15+
```console
16+
$ tmuxp load -d my-workspace.yaml
17+
```
18+
19+
## Load from a project directory
20+
21+
```console
22+
$ tmuxp load .
23+
```
24+
25+
## Freeze a running session
26+
27+
```console
28+
$ tmuxp freeze my-session
29+
```
30+
31+
## Convert YAML to JSON
32+
33+
```console
34+
$ tmuxp convert my-workspace.yaml
35+
```
36+
37+
## Convert JSON to YAML
38+
39+
```console
40+
$ tmuxp convert my-workspace.json
41+
```
42+
43+
## List available workspaces
44+
45+
```console
46+
$ tmuxp ls
47+
```
48+
49+
## Search workspaces
50+
51+
```console
52+
$ tmuxp search my-project
53+
```
54+
55+
## Edit a workspace config
56+
57+
```console
58+
$ tmuxp edit my-workspace
59+
```
60+
61+
## Collect debug info
62+
63+
```console
64+
$ tmuxp debug-info
65+
```
66+
67+
## Shell with tmux context
68+
69+
```console
70+
$ tmuxp shell
71+
```
72+
73+
Access libtmux objects directly:
74+
75+
```console
76+
$ tmuxp shell --best --command 'print(server.sessions)'
77+
```

‎docs/conf.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@
4444
"sphinxext.rediraffe",
4545
"myst_parser",
4646
"linkify_issues",
47+
"sphinx_design",
4748
]
4849

4950
myst_enable_extensions = [
@@ -54,6 +55,8 @@
5455
"linkify",
5556
]
5657

58+
myst_heading_anchors = 4
59+
5760
templates_path = ["_templates"]
5861

5962
source_suffix = {".rst": "restructuredtext", ".md": "markdown"}

‎docs/configuration/index.md‎

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -167,10 +167,33 @@ $ tmuxp load /opt/myapp
167167

168168
## Reference and usage
169169

170+
::::{grid} 3
171+
:gutter: 3
172+
173+
:::{grid-item-card} Top-level Options
174+
:link: top-level
175+
:link-type: doc
176+
Session and window configuration keys.
177+
:::
178+
179+
:::{grid-item-card} Environment Variables
180+
:link: environmental-variables
181+
:link-type: doc
182+
TMUXP_CONFIGDIR and other env vars.
183+
:::
184+
185+
:::{grid-item-card} Examples
186+
:link: examples
187+
:link-type: doc
188+
Sample workspace configurations.
189+
:::
190+
191+
::::
192+
170193
```{toctree}
194+
:hidden:
171195
172196
top-level
173197
environmental-variables
174198
examples
175-
176199
```

0 commit comments

Comments
 (0)