Skip to content

Commit b353f84

Browse files
tonytony
authored
Merge pull request #1029 from tmux-python/2026-spring-doc-redesign
docs(redesign) — CLI Frontend Skeleton pattern (#1029) Restructure tmuxp documentation to the CLI Frontend Documentation Skeleton. cli/ is the primary reference surface. Python API demoted to internals/. Standalone composed homepage. Grid cards on all section indexes. New CLI pages (exit-codes, recipes). Sidebar split (primary + "More"). 35 redirects. sphinx-design added.
2 parents 33da7da + 07c0ff9 commit b353f84

Some content is hidden

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

54 files changed

+739
-161
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)