API docs: hide +HIDE doctest setup, drop duplicate modifier badge#65
Merged
Conversation
why: A docstring often needs incidental setup (building an env mapping, a socket path) so its example executes, but that plumbing is noise to the reader. The doctest runner reads __doc__ from source, so rewriting the rendered docstring hides setup from the docs without affecting the test. what: - Add _strip_hidden_doctest_examples(lines), called first in process_docstring (before NumPy conversion). - Drop each `>>>` line carrying `# doctest: +HIDE` plus its `...` continuation lines. Covered by a module doctest.
why: A classmethod/staticmethod/async/abstract member rendered its modifier twice — once as the left signature prefix, once as the badge. what: - Add _strip_redundant_prefix(sig_node); call it from _inject_badges after modifier detection and slot injection. - Remove leading desc_sig_keyword nodes whose text is in _KEYWORD_TO_MOD (async/classmethod/static/abstract/abstractmethod/final) plus the trailing space; drop the annotation if it empties out. - Keyed off _KEYWORD_TO_MOD so detection and stripping never drift. Type-word prefixes (property/type) are left untouched. Covered by a module doctest.
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #65 +/- ##
=======================================
Coverage 92.64% 92.65%
=======================================
Files 273 273
Lines 21491 21520 +29
=======================================
+ Hits 19911 19939 +28
- Misses 1580 1581 +1 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
tony
added a commit
to tmux-python/libtmux
that referenced
this pull request
Jul 14, 2026
why: The socket_path/env plumbing that opens each from_env example is needed for the doctest to execute but is noise to the reader. Marking it hidden runs it as a test while keeping it out of the rendered docs. what: - Tag the setup lines in Server/Window/Pane.from_env with `# doctest: +HIDE`; split the env dicts so the marker fits <=88 cols. - Session.from_env hides only socket_path — its env carries the deliberately wrong session id the surrounding prose explains, so it stays visible (hide plumbing, not meaning). - TEMP: pin gp-libs / gp-sphinx to the branches carrying the HIDE optionflag and the render strip (git-pull/gp-libs#79, git-pull/gp-sphinx#65) via [tool.uv.sources]; revert to releases once they land.
tony
changed the title
+HIDE doctest setup, drop duplicate modifier badge
tony
added a commit
to tmux-python/libtmux
that referenced
this pull request
Jul 14, 2026
why: The socket_path/env plumbing that opens each from_env example is needed for the doctest to execute but is noise to the reader. Marking it hidden runs it as a test while keeping it out of the rendered docs. what: - Tag the setup lines in Server/Window/Pane.from_env with `# doctest: +HIDE`; split the env dicts so the marker fits <=88 cols. - Session.from_env hides only socket_path — its env carries the deliberately wrong session id the surrounding prose explains, so it stays visible (hide plumbing, not meaning). - TEMP: git-branch-pin the three changed packages (gp-libs, sphinx-autodoc-api-style, sphinx-autodoc-typehints-gp) to doctest-hide-badges; add typehints-gp as a direct dep so uv honors its source pin (uv.sources applies to direct deps only). gp-sphinx and its JS-asset packages stay on PyPI wheels, so CI needn't build the vite/pnpm toolchain. Revert to releases once git-pull/gp-libs#79 and git-pull/gp-sphinx#65 publish.
why: The branch taught the extension to drop +HIDE-flagged doctest
setup from rendered docstrings, but nothing told authors how to reach
for it or that the flag must be registered to keep running as a test.
what:
- Add a "Hiding incidental doctest setup" how-to section: illustrative
before/after plus the build-time-strip vs test-time-run distinction.
- Add a Features bullet so the capability is discoverable.
- Name the doctest.register_optionflag("HIDE") prerequisite and the
ValueError an unregistered flag raises.
why: Record the user-visible behavior this branch introduces as a merge-ready roll-up under the unreleased section. what: - Add What's new entry: +HIDE-tagged doctest lines still run but drop from rendered autodoc output. - Add Fixes entry: api-style modifier no longer renders twice (prefix plus badge) for classmethod/staticmethod/async/abstract members.
tony
force-pushed
the
doctest-hide-badges
branch
from
fc9df84 to
641a3ba
Compare
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
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.
Two independent API-documentation polish features (one PR, two commits).
1. Hide
# doctest: +HIDEexamples from render (typehints-gp)_strip_hidden_doctest_examples(lines), called first inprocess_docstring, drops each>>>line carrying# doctest: +HIDEplus its...continuations from the rendered docstring. The doctest runner reads__doc__from source, so the example still executes as a test — only the rendered docs lose the incidental setup (anenvmapping, a socket path).Pairs with the gp-libs
HIDEoptionflag registration (git-pull/gp-libs#79), which lets the marker parse instead of raisingValueError: invalid option.2. Drop the modifier prefix duplicated by the badge (
api-style)A classmethod/staticmethod/async/abstract member rendered its modifier twice: once as the left signature prefix, once as the badge.
_strip_redundant_prefix(sig_node)removes the leadingdesc_sig_keywordwhose text is in_KEYWORD_TO_MOD, keyed off that same map so detection and stripping never drift. Type-word prefixes (property/type) are left untouched.Tests
Both helpers carry module doctests (run via
--doctest-modules); the existingapi_stylesnapshot suite still passes unchanged.