Docstring fixes (#997)

Author: tony

CHANGES

@@ -31,7 +31,21 @@ $ pipx install --suffix=@next 'tmuxp' --pip-args '\--pre' --force
 
 <!-- To maintainers and contributors: Please add notes for the forthcoming version below -->
 
-_Future release notes will be placed here_
+_Upcoming changes will be written here._
+
+### Documentation (#997)
+
+Sphinx build warnings fixed:
+
+- `docs/conf.py`: Add sphinx-autodoc-typehints configuration
+  (`always_document_param_types`, `typehints_use_rtype`) and suppress
+  forward reference warnings from TYPE_CHECKING blocks
+- `src/tmuxp/workspace/builder.py`: Fix "via via" typo in docstring
+- `src/tmuxp/workspace/freezer.py`: Fix "workspacee" typo in docstring
+- `src/tmuxp/log.py`: Fix RST parameter formatting in docstrings
+- `src/tmuxp/workspace/finders.py`: Add missing Returns/Raises sections
+  to `find_workspace_file` docstring
+- `docs/about_tmux.md`: Fix orphan footnote reference
 
 ## tmuxp 1.59.0 (2025-11-30)
 

docs/about_tmux.md

@@ -572,7 +572,7 @@ line. The interval is determined by the `status-interval`:
 | `C-Up, C-Down` `C-Left, C-Right` | Resize the current pane in steps of one cell.                                                                              |
 | `M-Up, M-Down` `M-Left, M-Right` | Resize the current pane in steps of five cells.                                                                            |
 
-Source: tmux manpage[1].
+Source: tmux manpage[^id2].
 
 To get the text documentation of a `.1` manual file:
 

docs/conf.py

@@ -119,6 +119,16 @@
     "member-order": "bysource",
 }
 
+# sphinx-autodoc-typehints
+always_document_param_types = True
+typehints_use_rtype = False
+
+# Suppress warnings for forward references that can't be resolved
+# (types in TYPE_CHECKING blocks used for circular import avoidance)
+suppress_warnings = [
+    "sphinx_autodoc_typehints.forward_reference",
+]
+
 # sphinxext.opengraph
 ogp_site_url = about["__docs__"]
 ogp_image = "_static/img/icons/icon-192x192.png"

src/tmuxp/log.py

@@ -76,14 +76,13 @@ def template(
 
         Parameters
         ----------
-        :py:class:`logging.LogRecord` :
-            object. this is passed in from inside the
-            :py:meth:`logging.Formatter.format` record.
+        record : :py:class:`logging.LogRecord`
+            Object passed from :py:meth:`logging.Formatter.format`.
 
         Returns
         -------
         str
-            template for logger message
+            Template for logger message.
         """
         reset = Style.RESET_ALL
         levelname = set_style(
@@ -147,9 +146,8 @@ def debug_log_template(
 
     Parameters
     ----------
-    record :  :py:class:`logging.LogRecord`
-        This is passed in from inside the :py:meth:`logging.Formatter.format`
-        record.
+    record : :py:class:`logging.LogRecord`
+        Object passed from :py:meth:`logging.Formatter.format`.
 
     Returns
     -------

src/tmuxp/workspace/builder.py

@@ -110,7 +110,7 @@ class WorkspaceBuilder:
 
     The normal phase of loading is:
 
-    1. Load JSON / YAML file via via :class:`pathlib.Path`::
+    1. Load JSON / YAML file via :class:`pathlib.Path`::
 
            from tmuxp._internal import config_reader
            session_config = config_reader.ConfigReader._load(raw_yaml)

src/tmuxp/workspace/finders.py

@@ -153,11 +153,21 @@ def find_workspace_file(
     Parameters
     ----------
     workspace_file : str
-        workspace file, valid examples:
+        Workspace file, valid examples:
 
         - a file name, my_workspace.yaml
         - relative path, ../my_workspace.yaml or ../project
         - a period, .
+
+    Returns
+    -------
+    str
+        Resolved absolute path to workspace file.
+
+    Raises
+    ------
+    FileNotFoundError
+        If workspace file cannot be found.
     """
     if not workspace_dir:
         workspace_dir = get_workspace_dir()

src/tmuxp/workspace/freezer.py

@@ -52,7 +52,7 @@ def inline(workspace_dict: dict[str, t.Any]) -> t.Any:
 
 
 def freeze(session: Session) -> dict[str, t.Any]:
-    """Freeze live tmux session into a tmuxp workspacee.
+    """Freeze live tmux session into a tmuxp workspace.
 
     Parameters
     ----------