docs(pytest-plugin): Add pytest plugin page

Author: tony

docs/developing.md

@@ -23,6 +23,14 @@ Makefile commands prefixed with `watch_` will watch files and rerun.
 Helpers: `make test`
 Rerun tests on file change: `make watch_test` (requires [entr(1)])
 
+### Pytest plugin
+
+:::{seealso}
+
+See {ref}`pytest_plugin`.
+
+:::
+
 ## Documentation
 
 Default preview server: http://localhost:8023

docs/index.md

@@ -28,6 +28,7 @@ api
 :hidden:
 
 developing
+pytest-plugin
 internals/index
 history
 glossary

docs/pytest-plugin.md

@@ -0,0 +1,69 @@
+(pytest_plugin)=
+
+# `pytest` plugin
+
+Testing tmux with libtmux
+
+```{seealso} Using libtmux?
+
+Do you want more flexbility? Correctness? Power? Defaults changed? [Connect with us] on the tracker, we want to know
+your case, we won't stabilize APIs until we're sure everything is by the book.
+
+[connect with us]: https://github.com/tmux-python/libtmux/discussions
+
+```
+
+```{module} libtmux.pytest_plugin
+
+```
+
+## Usage
+
+Install `libtmux` via the python package manager of your choosing, e.g.
+
+```console
+$ pip install libtmux
+```
+
+The pytest plugin will automatically be detected via pytest, and the fixtures will be added.
+
+## Fixtures
+
+`pytest-tmux` works through providing {ref}`pytest fixtures <pytest:fixtures-api>` - so read up on
+those!
+
+The plugin's fixtures guarantee a fresh, headless `tmux(1)` server, session, window, or pane is
+passed into your test.
+
+## Autoused fixtures
+
+These are fixtures are automatically used when the plugin is enabled and `pytest` is ran.
+
+- Creating temporary, test directories for:
+  - `/home/` ({func}`home_path`)
+  - `/home/${user}` ({func}`user_path`)
+- Setting default .zshrc ({func}`zshrc`)
+- Default `.tmux.conf` configuration with these settings ({func}`config_file`):
+
+  - `base-index -g 1`
+  - `pane-base-index -g 1`
+
+  This are set to ensure panes and windows can be reliably referenced and asserted.
+
+## See examples
+
+View libtmux's own [tests/](https://github.com/tmux-python/libtmux/tree/master/tests) as well as
+tmuxp's [tests/](https://github.com/tmux-python/tmuxp/tree/master/tests).
+
+## API reference
+
+```{eval-rst}
+.. autoapimodule:: libtmux.pytest_plugin
+    :members:
+    :inherited-members:
+    :private-members:
+    :show-inheritance:
+    :member-order: bysource
+    :exclude-members: Server, TEST_SESSION_PREFIX, get_test_session_name,
+        namer, logger
+```