Doc fixes #612
Merged
Doc fixes #612
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #612 +/- ##
=======================================
Coverage 44.46% 44.46%
=======================================
Files 22 22
Lines 2305 2305
Branches 362 362
=======================================
Hits 1025 1025
Misses 1133 1133
Partials 147 147 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
tony
force-pushed
the
docstring-fixes
branch
2 times, most recently
from
92ec7bf to
f6fdc4f
Compare
why: Make pathlib available at documentation build time for type hints what: - Move pathlib import from TYPE_CHECKING block to regular imports - Fixes forward reference resolution in sphinx-autodoc-typehints
why: Ensure consistent parameter documentation in autodoc output what: - Add always_document_param_types = True for sphinx-autodoc-typehints
tony
force-pushed
the
docstring-fixes
branch
2 times, most recently
from
3da480d to
a79735c
Compare
Member
Author
Code reviewNo issues found. Checked for bugs and CLAUDE.md compliance. 🤖 Generated with Claude Code |
tony
force-pushed
the
docstring-fixes
branch
3 times, most recently
from
38c0ad5 to
90ebcee
Compare
why: Sphinx/myst was warning about jumping from H2 to H4 what: - Change #### (H4) subsection headers to ### (H3) in both files for proper header level hierarchy (H1 -> H2 -> H3)
why: Myst was warning about duplicate markdown reference definitions what: - Remove duplicate [uv] reference in developing.md - Remove duplicate [uv] reference in CHANGES - Remove duplicate [ptpython] reference in quickstart.md
why: Forward references in TYPE_CHECKING blocks cannot be resolved at
doc build time, causing ~69 warnings that obscure other issues
what:
- Add suppress_warnings config to hide forward_reference warnings
- These warnings are cosmetic - types like Self, Server, Session are
used as string forward references to avoid circular imports
…liance why: Sphinx/Napoleon requires proper field list structure to avoid "Field list ends without a blank line" warnings when processing NumPy-style docstrings. what: - Add Raises sections to EnvironmentMixin methods (common.py) - Add Returns sections to capture_pane, display_message, set_width, set_height (pane.py) - Fix attached_sessions Returns format (server.py) - Add Raises section to kill_window (session.py) - Add Returns/Raises sections to split, select_layout, move_window (window.py) - Standardize parameter descriptions (capitalize, add periods)
why: Dataclasses without docstrings cause "Inline strong start-string without end-string" warnings. Citation syntax [1]_ not resolving properly. what: - Add docstrings to ServerOptions, SessionOptions, WindowOptions, PaneOptions, Options dataclasses (constants.py) - Simplify EnvironmentVarGuard docstring, convert citation to inline URL (environment.py)
why: Sphinx warns about duplicate labels, undefined references, and strikethrough syntax not supported in non-HTML output. what: - Remove duplicate (internals)= label from about.md - Add (setting_a_tmux_configuration)= label and fix reference in pytest-plugin/index.md - Replace ~~strikethrough~~ with italicized note in CHANGES
why: sphinx-autodoc-typehints was injecting :type: and :rtype: directives into docstrings at runtime, causing "Unexpected indentation" errors due to RST field list parsing conflicts with Napoleon-processed docstrings. what: - Change autodoc_typehints from "description" to "signature" - Set always_document_param_types = False to disable param type injection - Set typehints_document_rtype = False to disable return type injection - Type hints are now visible in function signatures only This eliminates all 64 anonymous "Unexpected indentation" errors while maintaining type documentation in the API reference.
…message why: The return type annotations incorrectly included `str` as a possible return type, but the implementation only ever returns `list[str]`. what: - Change capture_pane() return type from `str | list[str]` to `list[str]` - Change display_message() return type from `str | list[str] | None` to `list[str] | None` - Update corresponding docstring Returns sections
…ypehints why: Types in TYPE_CHECKING blocks (used for circular import avoidance) cause sphinx-autodoc-typehints to emit warnings about unresolvable forward references. These warnings are expected and safe to suppress. what: - Add suppress_warnings config for sphinx_autodoc_typehints.forward_reference
why: Sphinx warns about duplicate object descriptions when the same module is referenced in multiple documentation files. what: - Add :no-index: directive to module blocks in windows.md, pytest-plugin/index.md, and quickstart.md to prevent duplicate indexing
why: Users relying on type hints should know about the corrected return types. what: - Add changelog entry for capture_pane() and display_message() type fixes
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Problem
Various sphinx warnings on build. Let's tackle those.