Skip to content

Commit ab887fd

Browse files
committed
docs(README): add topic links and pytest fixture example
why: Following libvcs pattern, each code example should link to deeper documentation for users who want to learn more. what: - Add "Learn more" links to quickstart sections (workspace setup, pane interaction, traversal, pytest plugin) - Add inline links in features list (traverse, context managers, pytest) - Add pytest fixture code example showing session fixture usage - Reorganize project links into Topics / Reference / Project groups - Link all 6 topic pages: traversal, pane_interaction, workspace_setup, automation_patterns, context_managers, options_and_hooks
1 parent 0e0d408 commit ab887fd

File tree

1 file changed

+49
-17
lines changed

1 file changed

+49
-17
lines changed

README.md

Lines changed: 49 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -22,11 +22,11 @@ libtmux is a typed Python API over [tmux], the terminal multiplexer. Stop shelli
2222
### ✨ Features
2323

2424
- Typed, object-oriented control of tmux state
25-
- Query and traverse live sessions, windows, and panes
25+
- Query and [traverse](https://libtmux.git-pull.com/topics/traversal.html) live sessions, windows, and panes
2626
- Raw escape hatch via `.cmd(...)` on any object
2727
- Works with multiple tmux sockets and servers
28-
- Context managers for automatic cleanup
29-
- pytest plugin for isolated tmux fixtures
28+
- [Context managers](https://libtmux.git-pull.com/topics/context_managers.html) for automatic cleanup
29+
- [pytest plugin](https://libtmux.git-pull.com/pytest-plugin/index.html) for isolated tmux fixtures
3030
- Proven in production via tmuxp and other tooling
3131

3232
## Requirements & support
@@ -155,6 +155,8 @@ Session($... ...)
155155

156156
### Control sessions and windows
157157

158+
[**Learn more about Workspace Setup**](https://libtmux.git-pull.com/topics/workspace_setup.html)
159+
158160
```python
159161
>>> session.rename_session('my-session')
160162
Session($... my-session)
@@ -178,6 +180,8 @@ Window(@... ...:bg-work, Session($... ...))
178180

179181
### Split windows and send keys
180182

183+
[**Learn more about Pane Interaction**](https://libtmux.git-pull.com/topics/pane_interaction.html)
184+
181185
```python
182186
>>> pane = window.split(attach=False)
183187
>>> pane
@@ -205,6 +209,8 @@ Pane(%... ...)
205209

206210
### Traverse the hierarchy
207211

212+
[**Learn more about Traversal**](https://libtmux.git-pull.com/topics/traversal.html)
213+
208214
Navigate from pane up to window to session:
209215

210216
```python
@@ -243,12 +249,25 @@ pane.send_keys("echo 'hello from libtmux'", enter=True)
243249

244250
## Testing & fixtures
245251

246-
- [pytest plugin][pytest-plugin] provides fresh tmux server/session/window/pane fixtures
252+
[**Learn more about the pytest plugin**](https://libtmux.git-pull.com/pytest-plugin/index.html)
253+
254+
Writing a tool that interacts with tmux? Use our fixtures to keep your tests clean and isolated.
255+
256+
```python
257+
def test_my_tmux_tool(session):
258+
# session is a real tmux session in an isolated server
259+
window = session.new_window(window_name="test")
260+
pane = window.active_pane
261+
pane.send_keys("echo 'hello from test'", enter=True)
262+
263+
assert window.window_name == "test"
264+
# Fixtures handle cleanup automatically
265+
```
266+
267+
- Fresh tmux server/session/window/pane fixtures per test
247268
- Temporary HOME and tmux config fixtures keep indices stable
248269
- `TestServer` helper spins up multiple isolated tmux servers
249270

250-
[pytest-plugin]: https://libtmux.git-pull.com/pytest-plugin/index.html
251-
252271
## When you might not need libtmux
253272

254273
- Layouts are static and live entirely in tmux config files
@@ -257,17 +276,30 @@ pane.send_keys("echo 'hello from libtmux'", enter=True)
257276

258277
## Project links
259278

260-
- Docs: [docs]
261-
- API reference: [api]
262-
- Architecture: [architecture]
263-
- Changelog: [history]
264-
- Migration notes: [migration]
265-
- Issues: [issues]
266-
- Test coverage: [coverage]
267-
- Releases: [releases]
268-
- License: [license]
269-
- Support: [support]
270-
- **[The Tao of tmux][tao]** — deep-dive book on tmux fundamentals
279+
**Topics:**
280+
[Traversal](https://libtmux.git-pull.com/topics/traversal.html) ·
281+
[Pane Interaction](https://libtmux.git-pull.com/topics/pane_interaction.html) ·
282+
[Workspace Setup](https://libtmux.git-pull.com/topics/workspace_setup.html) ·
283+
[Automation Patterns](https://libtmux.git-pull.com/topics/automation_patterns.html) ·
284+
[Context Managers](https://libtmux.git-pull.com/topics/context_managers.html) ·
285+
[Options & Hooks](https://libtmux.git-pull.com/topics/options_and_hooks.html)
286+
287+
**Reference:**
288+
[Docs][docs] ·
289+
[API][api] ·
290+
[pytest plugin](https://libtmux.git-pull.com/pytest-plugin/index.html) ·
291+
[Architecture][architecture] ·
292+
[Changelog][history] ·
293+
[Migration][migration]
294+
295+
**Project:**
296+
[Issues][issues] ·
297+
[Coverage][coverage] ·
298+
[Releases][releases] ·
299+
[License][license] ·
300+
[Support][support]
301+
302+
**[The Tao of tmux][tao]** — deep-dive book on tmux fundamentals
271303

272304
## Contributing & support
273305

0 commit comments

Comments
 (0)