From a12fb297ac6a1ee73138e86f3bc2ff8b8fc4e51d Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sat, 6 Dec 2025 06:09:39 -0600 Subject: [PATCH 1/6] docs(conf): Add sphinx-autodoc-typehints config, suppress forward ref warnings - Add always_document_param_types = True for consistent parameter docs - Add typehints_use_rtype = False to embed return types inline - Suppress sphinx_autodoc_typehints.forward_reference warnings for types in TYPE_CHECKING blocks (used for circular import avoidance) This eliminates ~26 forward reference warnings from the docs build. --- docs/conf.py | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 81c72be345..7a4270e5b0 100644 --- a/docs/conf.py +++ b/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" From 35ac92cf2ed5841cd48c621ace5fe2821a11c906 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sat, 6 Dec 2025 06:10:00 -0600 Subject: [PATCH 2/6] docs(docstrings): Fix typos in workspace module docstrings - builder.py: Remove duplicate "via" in loading phase documentation - freezer.py: Fix "workspacee" typo to "workspace" --- src/tmuxp/workspace/builder.py | 2 +- src/tmuxp/workspace/freezer.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/tmuxp/workspace/builder.py b/src/tmuxp/workspace/builder.py index 6b9d482ddc..31f76b97f8 100644 --- a/src/tmuxp/workspace/builder.py +++ b/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) diff --git a/src/tmuxp/workspace/freezer.py b/src/tmuxp/workspace/freezer.py index d1e5ead92f..8807e9e43e 100644 --- a/src/tmuxp/workspace/freezer.py +++ b/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 ---------- From ad02c311f0b77135984ee57cbacba7b3a6e166da Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sat, 6 Dec 2025 06:10:35 -0600 Subject: [PATCH 3/6] docs(docstrings): Fix RST parameter formatting in log.py - Fix malformed NumPy-style parameter documentation in template() - Fix double space in debug_log_template() parameter line - Standardize parameter descriptions to be concise --- src/tmuxp/log.py | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/src/tmuxp/log.py b/src/tmuxp/log.py index 613b140a65..6e53ab05b5 100644 --- a/src/tmuxp/log.py +++ b/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 ------- From 8d6c3d5d59d79ee6b8a218ce02c7deb5da3d95ea Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sat, 6 Dec 2025 06:12:05 -0600 Subject: [PATCH 4/6] docs(docstrings): Fix RST formatting in find_workspace_file docstring Add missing Returns and Raises sections to complete the NumPy-style docstring and fix RST field list parsing error. --- src/tmuxp/workspace/finders.py | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/src/tmuxp/workspace/finders.py b/src/tmuxp/workspace/finders.py index a4edfef7ec..f8229bc26a 100644 --- a/src/tmuxp/workspace/finders.py +++ b/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() From 990155e535e8dd37a33750729557e73c514fd995 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sat, 6 Dec 2025 06:12:49 -0600 Subject: [PATCH 5/6] docs(about_tmux): Fix orphan footnote reference Change [1] to [^id2] to properly reference the defined footnote for the tmux manpage source link. --- docs/about_tmux.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/about_tmux.md b/docs/about_tmux.md index 5cb20f86c7..5f10e2275e 100644 --- a/docs/about_tmux.md +++ b/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: From 0f440244b0fefa3f3b3d55ebc5f57b45f4f51f52 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sat, 6 Dec 2025 07:57:59 -0600 Subject: [PATCH 6/6] docs(CHANGES): Note Sphinx warning fixes --- CHANGES | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/CHANGES b/CHANGES index 09ef398e94..dece792757 100644 --- a/CHANGES +++ b/CHANGES @@ -31,7 +31,21 @@ $ pipx install --suffix=@next 'tmuxp' --pip-args '\--pre' --force -_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)