Doc improvements

conftest.py

@@ -1,11 +1,14 @@
-"""Conftest.py (root-level).
+"""Configure root-level pytest fixtures for libtmux.
 
-We keep this in root pytest fixtures in pytest's doctest plugin to be available, as well
-as avoiding conftest.py from being included in the wheel, in addition to pytest_plugin
-for pytester only being available via the root directory.
+We keep this file at the root to make these fixtures available to all
+tests, while also preventing unwanted inclusion in the distributed
+wheel. Additionally, `pytest_plugins` references ensure that the
+`pytester` plugin is accessible for test generation and execution.
 
-See "pytest_plugins in non-top-level conftest files" in
-https://docs.pytest.org/en/stable/deprecations.html
+See Also
+--------
+pytest_plugins in non-top-level conftest files
+    https://docs.pytest.org/en/stable/deprecations.html
 """
 
 from __future__ import annotations
@@ -35,7 +38,13 @@ def add_doctest_fixtures(
     request: pytest.FixtureRequest,
     doctest_namespace: dict[str, t.Any],
 ) -> None:
-    """Configure doctest fixtures for pytest-doctest."""
+    """Configure doctest fixtures for pytest-doctest.
+
+    Automatically sets up tmux-related classes and default fixtures,
+    making them available in doctest namespaces if `tmux` is found
+    on the system. This ensures that doctest blocks referencing tmux
+    structures can execute smoothly in the test environment.
+    """
     if isinstance(request._pyfuncitem, DoctestItem) and shutil.which("tmux"):
         request.getfixturevalue("set_home")
         doctest_namespace["Server"] = Server
@@ -63,22 +72,26 @@ def set_home(
     monkeypatch: pytest.MonkeyPatch,
     user_path: pathlib.Path,
 ) -> None:
-    """Configure home directory for pytest tests."""
+    """Set the HOME environment variable to the temporary user directory."""
     monkeypatch.setenv("HOME", str(user_path))
 
 
 @pytest.fixture(autouse=True)
 def setup_fn(
     clear_env: None,
 ) -> None:
-    """Function-level test configuration fixtures for pytest."""
+    """Apply function-level test fixture configuration (e.g., environment cleanup)."""
 
 
 @pytest.fixture(autouse=True, scope="session")
 def setup_session(
     request: pytest.FixtureRequest,
     config_file: pathlib.Path,
 ) -> None:
-    """Session-level test configuration for pytest."""
+    """Apply session-level test fixture configuration for libtmux testing.
+
+    If zsh is in use, applies a suppressing `.zshrc` fix to avoid
+    default interactive messages that might disrupt tmux sessions.
+    """
     if USING_ZSH:
         request.getfixturevalue("zshrc")

pyproject.toml

@@ -138,6 +138,10 @@ files = [
   "tests",
 ]
 
+[[tool.mypy.overrides]]
+module = "tests.examples.pytest_plugin.*"
+disallow_untyped_defs = false
+disallow_incomplete_defs = false
 
 [tool.coverage.run]
 branch = true

src/libtmux/pytest_plugin.py

@@ -1,4 +1,16 @@
-"""libtmux pytest plugin."""
+"""Provide a pytest plugin that supplies libtmux testing fixtures.
+
+This plugin integrates with pytest to offer session, window, and environment
+fixtures tailored for tmux-based tests. It ensures stable test environments by
+creating and tearing down temporary sessions and windows for each test as
+needed.
+
+Notes
+-----
+The existing doctests embedded within each fixture are preserved to maintain
+clarity and verify core behaviors.
+
+"""
 
 from __future__ import annotations
 
@@ -100,7 +112,8 @@ def config_file(user_path: pathlib.Path) -> pathlib.Path:
 
     - ``base-index -g 1``
 
-    These guarantee pane and windows targets can be reliably referenced and asserted.
+    These guarantee pane and windows targets can be reliably referenced
+    and asserted.
 
     Note: You will need to set the home directory, see :ref:`set_home`.
     """
@@ -118,7 +131,8 @@ def config_file(user_path: pathlib.Path) -> pathlib.Path:
 def clear_env(monkeypatch: pytest.MonkeyPatch) -> None:
     """Clear out any unnecessary environment variables that could interrupt tests.
 
-    tmux show-environment tests were being interrupted due to a lot of crazy env vars.
+    tmux show-environment tests were being interrupted due to a lot of
+    crazy env vars.
     """
     for k in os.environ:
         if not any(