Skip to content

Commit 1645225

Browse files
tonytony
committed
docs(api[structure]): restructure api/ with testing/ subtree and project/ governance
why: api/ mixed core reference, testing utilities, and policy pages at the same level — testing tools were buried, governance docs didn't belong in the API namespace, and toctrees rendered as visible bullet lists on the landing page. what: - Create docs/api/testing/ subtree; pytest-plugin and test-helpers each get a landing → usage → reference leaf hierarchy - Split api/pytest-plugin/index.md into usage.md + fixtures.md under docs/api/testing/pytest-plugin/ - Move policy docs (public-api, compatibility, deprecations) from docs/api/ to docs/project/ where governance belongs - Rewrite docs/api/index.md: task grid, Testing card, API Policy grid; all toctrees now :hidden: (removes visible bullet lists) - Add API Governance section to docs/project/index.md - Update cross-links in topics/public-vs-internal.md, topics/design-decisions.md, docs/index.md - Add redirects for all moved pages; update historical aliases to point at final destinations (avoids redirect chains)
1 parent f8d1e50 commit 1645225

21 files changed

Lines changed: 277 additions & 80 deletions

‎docs/api/index.md‎

Lines changed: 76 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,38 @@
55
# API Reference
66

77
libtmux's public API mirrors tmux's object hierarchy:
8+
`Server` → `Session` → `Window` → `Pane`
89

9-
```
10-
Server -> Session -> Window -> Pane
11-
```
10+
## What do you want to do?
11+
12+
::::{grid} 1 2 2 2
13+
:gutter: 2
14+
15+
:::{grid-item-card} Find a session, window, or pane?
16+
:link: libtmux.server
17+
:link-type: doc
18+
Use `server.sessions.get()`, `session.windows.get()`.
19+
:::
20+
21+
:::{grid-item-card} Send commands or keys to a terminal?
22+
:link: libtmux.pane
23+
:link-type: doc
24+
Use `pane.send_keys()` and `pane.enter()`.
25+
:::
26+
27+
:::{grid-item-card} Capture output from a pane?
28+
:link: libtmux.pane
29+
:link-type: doc
30+
Use `pane.capture_pane()`.
31+
:::
32+
33+
:::{grid-item-card} Write tests against tmux?
34+
:link: testing/index
35+
:link-type: doc
36+
Use the pytest plugin and test helpers.
37+
:::
38+
39+
::::
1240

1341
## Core Objects
1442

@@ -84,39 +112,59 @@ Exception hierarchy.
84112

85113
::::
86114

87-
```{toctree}
88-
:hidden:
89-
:maxdepth: 1
115+
## Testing
90116

91-
libtmux.server
92-
libtmux.session
93-
libtmux.window
94-
libtmux.pane
95-
libtmux.common
96-
libtmux.neo
97-
libtmux.options
98-
libtmux.hooks
99-
libtmux.constants
100-
libtmux.exc
101-
```
117+
::::{grid} 1 1 1 1
118+
:gutter: 2
102119

103-
## Test Utilities
120+
:::{grid-item-card} Testing Utilities
121+
:link: testing/index
122+
:link-type: doc
123+
pytest plugin, fixtures, and test helpers for testing code that uses libtmux.
124+
:::
104125

105-
If you're testing code that uses libtmux, see the test helpers and pytest plugin:
126+
::::
106127

107-
```{toctree}
108-
:maxdepth: 1
128+
## API Policy and Guarantees
109129

110-
test-helpers/index
111-
pytest-plugin/index
112-
```
130+
These documents define the project's promises about the public API.
113131

114-
## API Contract
132+
::::{grid} 1 2 3 3
133+
:gutter: 2
134+
135+
:::{grid-item-card} Public API
136+
:link: ../project/public-api
137+
:link-type: doc
138+
What is and is not considered stable public API.
139+
:::
140+
141+
:::{grid-item-card} Compatibility
142+
:link: ../project/compatibility
143+
:link-type: doc
144+
Supported versions of Python and tmux.
145+
:::
146+
147+
:::{grid-item-card} Deprecations
148+
:link: ../project/deprecations
149+
:link-type: doc
150+
Active deprecations and migration guidance.
151+
:::
152+
153+
::::
115154

116155
```{toctree}
156+
:hidden:
117157
:maxdepth: 1
118158
119-
public-api
120-
compatibility
121-
deprecations
159+
Server <libtmux.server>
160+
Session <libtmux.session>
161+
Window <libtmux.window>
162+
Pane <libtmux.pane>
163+
Common <libtmux.common>
164+
Neo <libtmux.neo>
165+
Options <libtmux.options>
166+
Hooks <libtmux.hooks>
167+
Constants <libtmux.constants>
168+
Exceptions <libtmux.exc>
169+
Testing Utilities <testing/index>
122170
```

‎docs/api/test-helpers/index.md‎

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

‎docs/api/testing/index.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
(testing)=
2+
3+
# Testing Utilities
4+
5+
Tools for testing code that uses libtmux.
6+
7+
::::{grid} 1 1 2 2
8+
:gutter: 2 2 3 3
9+
10+
:::{grid-item-card} pytest Plugin
11+
:link: pytest-plugin/index
12+
:link-type: doc
13+
Fixtures for isolated tmux servers, sessions, windows, and panes in automated tests.
14+
:::
15+
16+
:::{grid-item-card} Test Helpers
17+
:link: test-helpers/index
18+
:link-type: doc
19+
Utilities for test setup: constants, environment mocking, retry logic, temporary resources.
20+
:::
21+
22+
::::
23+
24+
```{toctree}
25+
:hidden:
26+
:maxdepth: 2
27+
28+
pytest-plugin/index
29+
test-helpers/index
30+
```

‎docs/api/testing/pytest-plugin/fixtures.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
(pytest_plugin_fixtures)=
2+
3+
# Fixture Reference
4+
5+
```{eval-rst}
6+
.. automodule:: libtmux.pytest_plugin
7+
:members:
8+
:inherited-members:
9+
:private-members:
10+
:show-inheritance:
11+
:member-order: bysource
12+
```

‎docs/api/testing/pytest-plugin/index.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
(pytest_plugin)=
2+
3+
# pytest Plugin
4+
5+
libtmux's pytest plugin provides fixtures for isolated tmux servers, sessions, windows, and panes
6+
in automated tests.
7+
8+
::::{grid} 1 1 2 2
9+
:gutter: 2 2 3 3
10+
11+
:::{grid-item-card} Usage Guide
12+
:link: usage
13+
:link-type: doc
14+
Setup, configuration, custom session parameters, temporary servers.
15+
:::
16+
17+
:::{grid-item-card} Fixture Reference
18+
:link: fixtures
19+
:link-type: doc
20+
Complete autodoc for all fixtures and plugin API.
21+
:::
22+
23+
::::
24+
25+
```{toctree}
26+
:hidden:
27+
:maxdepth: 1
28+
29+
usage
30+
fixtures
31+
```

docs/api/pytest-plugin/index.md renamed to docs/api/testing/pytest-plugin/usage.md

Lines changed: 4 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
(pytest_plugin)=
1+
(pytest_plugin_usage)=
22

3-
# tmux `pytest` plugin
3+
# Usage Guide
44

55
libtmux provides pytest fixtures for tmux. The plugin automatically manages setup and teardown of an
66
independent tmux server.
@@ -11,9 +11,6 @@ Do you want more flexibility? Correctness? Power? Defaults changed? [Connect wit
1111
your case, we won't stabilize APIs until we're sure everything is by the book.
1212
1313
[connect with us]: https://github.com/tmux-python/libtmux/discussions
14-
15-
```{module} libtmux.pytest_plugin
16-
:no-index:
1714
```
1815

1916
## Usage
@@ -103,7 +100,7 @@ If you need multiple independent tmux servers in your tests, the {func}`TestServ
103100
def test_something(TestServer):
104101
Server = TestServer() # Get unique partial'd Server
105102
server = Server() # Create server instance
106-
103+
107104
session = server.new_session()
108105
assert server.is_alive()
109106
```
@@ -114,7 +111,7 @@ You can also use it with custom configurations, similar to the {ref}`server fixt
114111
def test_with_config(TestServer, tmp_path):
115112
config_file = tmp_path / "tmux.conf"
116113
config_file.write_text("set -g status off")
117-
114+
118115
Server = TestServer()
119116
server = Server(config_file=str(config_file))
120117
```
@@ -136,14 +133,3 @@ def set_home(
136133
):
137134
monkeypatch.setenv("HOME", str(user_path))
138135
```
139-
140-
## Fixtures
141-
142-
```{eval-rst}
143-
.. automodule:: libtmux.pytest_plugin
144-
:members:
145-
:inherited-members:
146-
:private-members:
147-
:show-inheritance:
148-
:member-order: bysource
149-
```

docs/api/test-helpers/constants.md renamed to docs/api/testing/test-helpers/constants.md

File renamed without changes.

docs/api/test-helpers/environment.md renamed to docs/api/testing/test-helpers/environment.md

File renamed without changes.

‎docs/api/testing/test-helpers/index.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
(test_helpers)=
2+
3+
# Test Helpers
4+
5+
Utilities for writing reliable tests against libtmux and downstream code that uses tmux.
6+
7+
::::{grid} 1 2 3 3
8+
:gutter: 2 2 3 3
9+
10+
:::{grid-item-card} libtmux.test
11+
:link: libtmux.test
12+
:link-type: doc
13+
Base test module with common setup utilities.
14+
:::
15+
:::{grid-item-card} Constants
16+
:link: constants
17+
:link-type: doc
18+
Predefined test constants.
19+
:::
20+
:::{grid-item-card} Environment
21+
:link: environment
22+
:link-type: doc
23+
Environment variable mocking.
24+
:::
25+
:::{grid-item-card} Random
26+
:link: random
27+
:link-type: doc
28+
Randomized name generators.
29+
:::
30+
:::{grid-item-card} Retry
31+
:link: retry
32+
:link-type: doc
33+
Retry logic for async/tmux operations.
34+
:::
35+
:::{grid-item-card} Temporary
36+
:link: temporary
37+
:link-type: doc
38+
Context managers for ephemeral tmux resources.
39+
:::
40+
41+
::::
42+
43+
```{toctree}
44+
:hidden:
45+
:maxdepth: 1
46+
47+
libtmux.test
48+
constants
49+
environment
50+
random
51+
retry
52+
temporary
53+
```

‎docs/api/testing/test-helpers/libtmux.test.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
(test_helpers_base)=
2+
3+
# libtmux.test
4+
5+
Base test utilities for libtmux and downstream libraries.
6+
7+
```{eval-rst}
8+
.. automodule:: libtmux.test
9+
:members:
10+
:undoc-members:
11+
:show-inheritance:
12+
:member-order: bysource
13+
```

0 commit comments

Comments
 (0)