docs(pytest-plugin): restructure fixture reference with autofixture directives

why: The previous fixture reference used a single automodule dump that
rendered fixtures as plain functions. The new page uses autofixture
directives to show fixtures grouped by purpose (core, environment,
override hooks, factories) with a decision guide and configuration
reference.
what:
- Rewrite docs/api/testing/pytest-plugin/fixtures.md with Quick Start
  section, "Which Fixture Do I Need?" guide, autofixture-index table,
  grouped autofixture directives with inline examples, and confval
  configuration reference
- Update docs/api/testing/pytest-plugin/usage.md to change {func} xrefs
  to {fixture} xrefs (home_path, user_path, config_file, session,
  server, session_params, TestServer) to match the new domain objects

Author: tony

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

@@ -1,12 +1,159 @@
 (pytest_plugin_fixtures)=
 
-# Fixture Reference
+# Fixtures
+
+## Quick Start
+
+Add a fixture name as a test parameter — pytest creates and injects it automatically. You never call fixtures yourself.
+
+```python
+def test_basic(server: Server) -> None:
+    session = server.new_session(session_name="my-session")
+    assert session is not None
+
+
+def test_with_session(session: Session) -> None:
+    window = session.new_window(window_name="test")
+    assert window is not None
+```
+
+## Which Fixture Do I Need?
+
+- Use {fixture}`session` when you want a ready-to-use tmux session.
+- Use {fixture}`server` when you want a bare server and will create sessions yourself.
+- Use {fixture}`TestServer` when you need multiple isolated servers in one test.
+- Override {fixture}`session_params` when you need custom session creation.
+- Override {fixture}`home_user_name` when you need a custom test user.
+- Request {fixture}`clear_env` when testing tmux behavior with a minimal environment.
+
+## Fixture Summary
+
+```{autofixture-index} libtmux.pytest_plugin
+```
+
+---
+
+## Core Fixtures
+
+The primary injection points for libtmux tests.
+
+```{eval-rst}
+.. autofixture:: libtmux.pytest_plugin.server
+
+   .. rubric:: Example
+
+   .. code-block:: python
+
+      def test_server_sessions(server: Server) -> None:
+          session = server.new_session(session_name="work")
+          assert session.session_name == "work"
+
+.. autofixture:: libtmux.pytest_plugin.session
+
+   .. rubric:: Example
+
+   .. code-block:: python
+
+      def test_session_windows(session: Session) -> None:
+          window = session.new_window(window_name="editor")
+          assert window.window_name == "editor"
+```
+
+## Environment Fixtures
+
+Session-scoped fixtures that create an isolated filesystem environment.
+Shared across all tests in a session — created once, reused everywhere.
+
+```{eval-rst}
+.. autofixture:: libtmux.pytest_plugin.home_path
+
+.. autofixture:: libtmux.pytest_plugin.user_path
+
+.. autofixture:: libtmux.pytest_plugin.config_file
+
+.. autofixture:: libtmux.pytest_plugin.zshrc
+```
+
+## Override Hooks
+
+Override these in your project's `conftest.py` to customise the test environment.
+
+```{eval-rst}
+.. autofixture:: libtmux.pytest_plugin.home_user_name
+   :kind: override_hook
+
+.. autofixture:: libtmux.pytest_plugin.session_params
+   :kind: override_hook
+
+   .. rubric:: Example
+
+   .. code-block:: python
+
+      # conftest.py
+      @pytest.fixture
+      def session_params() -> dict:
+          return {"x": 800, "y": 600}
+```
+
+## Factories
+
+```{eval-rst}
+.. autofixture:: libtmux.pytest_plugin.TestServer
+```
+
+## Low-Level / Rarely Needed
 
 ```{eval-rst}
-.. automodule:: libtmux.pytest_plugin
-    :members:
-    :inherited-members:
-    :private-members:
-    :show-inheritance:
-    :member-order: bysource
+.. autofixture:: libtmux.pytest_plugin.clear_env
+```
+
+---
+
+## Configuration
+
+These `conf.py` values control how fixture documentation is rendered:
+
+```{eval-rst}
+.. confval:: pytest_fixture_hidden_dependencies
+
+   Fixture names to suppress from "Depends on" lists. Default: common pytest
+   builtins (:external+pytest:std:fixture:`pytestconfig`,
+   :external+pytest:std:fixture:`capfd`,
+   :external+pytest:std:fixture:`capsysbinary`,
+   :external+pytest:std:fixture:`capfdbinary`,
+   :external+pytest:std:fixture:`recwarn`,
+   :external+pytest:std:fixture:`tmpdir`,
+   :external+pytest:std:fixture:`pytester`,
+   :external+pytest:std:fixture:`testdir`,
+   :external+pytest:std:fixture:`record_property`,
+   ``record_xml_attribute``,
+   :external+pytest:std:fixture:`record_testsuite_property`,
+   :external+pytest:std:fixture:`cache`).
+
+.. confval:: pytest_fixture_builtin_links
+
+   URL mapping for builtin fixture external links in "Depends on" blocks.
+   Default: links to pytest docs for
+   :external+pytest:std:fixture:`tmp_path_factory`,
+   :external+pytest:std:fixture:`tmp_path`,
+   :external+pytest:std:fixture:`monkeypatch`,
+   :external+pytest:std:fixture:`request`,
+   :external+pytest:std:fixture:`capsys`,
+   :external+pytest:std:fixture:`caplog`.
+
+.. confval:: pytest_external_fixture_links
+
+   URL mapping for external fixture cross-references. Default: ``{}``.
+```
+
+---
+
+```{note}
+All fixtures above are also auto-discoverable via:
+
+    .. autofixtures:: libtmux.pytest_plugin
+       :order: source
+
+Use ``autofixtures::`` in your own plugin docs to document all fixtures from a
+module without listing each one manually.
 ```

docs/api/testing/pytest-plugin/usage.md

@@ -46,9 +46,9 @@ passed into your test.
 These fixtures are automatically used when the plugin is enabled and `pytest` is run.
 
 - Creating temporary, test directories for:
-  - `/home/` ({func}`home_path`)
-  - `/home/${user}` ({func}`user_path`)
-- Default `.tmux.conf` configuration with these settings ({func}`config_file`):
+  - `/home/` ({fixture}`home_path`)
+  - `/home/${user}` ({fixture}`user_path`)
+- Default `.tmux.conf` configuration with these settings ({fixture}`config_file`):
 
   - `base-index -g 1`
 
@@ -58,19 +58,19 @@ These fixtures are automatically used when the plugin is enabled and `pytest` is
 
 ## Setting a tmux configuration
 
-If you would like {func}`session fixture <libtmux.pytest_plugin.session>` to automatically use a configuration, you have a few
+If you would like {fixture}`session <libtmux.pytest_plugin.session>` to automatically use a configuration, you have a few
 options:
 
 - Pass a `config_file` into {class}`~libtmux.Server`
 - Set the `HOME` directory to a local or temporary pytest path with a configuration file
 
-You could also read the code and override {func}`server fixture <libtmux.pytest_plugin.server>` in your own doctest.
+You could also read the code and override {fixture}`server <libtmux.pytest_plugin.server>` in your own doctest.
 
 (custom_session_params)=
 
 ### Custom session parameters
 
-You can override `session_params` to customize the `session` fixture. The
+You can override {fixture}`session_params` to customize the `session` fixture. The
 dictionary will directly pass into {meth}`Server.new_session` keyword arguments.
 
 ```python
@@ -94,7 +94,7 @@ The above will assure the libtmux session launches with `-x 800 -y 600`.
 
 ### Creating temporary servers
 
-If you need multiple independent tmux servers in your tests, the {func}`TestServer fixture <libtmux.pytest_plugin.TestServer>` provides a factory that creates servers with unique socket names. Each server is automatically cleaned up when the test completes.
+If you need multiple independent tmux servers in your tests, the {fixture}`TestServer <libtmux.pytest_plugin.TestServer>` provides a factory that creates servers with unique socket names. Each server is automatically cleaned up when the test completes.
 
 ```python
 def test_something(TestServer):