doctest(feat[HIDE]): Register no-op +HIDE optionflag#79
Merged
Conversation
why: Let documentation tooling mark a doctest example to hide from rendered output while it still runs as a real test. Without the registration, `# doctest: +HIDE` raises ValueError: invalid option at collection time. what: - Register HIDE eagerly in pytest_configure, before collection. The .py docstring path delegates to pytest's own DoctestModule, which never calls our _get_flag_lookup, so import-time registration is load-bearing. - Add _get_hide_flag() and a HIDE entry in _get_flag_lookup for the .rst/.md path and ini use. - Test: `# doctest: +HIDE` in a .py docstring collects and runs as a no-op.
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## master #79 +/- ##
==========================================
+ Coverage 76.16% 76.32% +0.15%
==========================================
Files 15 15
Lines 1007 1018 +11
==========================================
+ Hits 767 777 +10
- Misses 240 241 +1 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
This was referenced Jul 14, 2026
tony
changed the title
+HIDE optionflag
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
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: Document the new +HIDE marker for the unreleased section. what: - Add "New doctest flag: +HIDE" under What's new
tony
added a commit
that referenced
this pull request
Jul 14, 2026
why: The +HIDE marker shipped in #79 with only a CHANGES entry; the docs site had no how-to explaining when or why to reach for it. what: - Add a "Hide a setup line from rendered docs" section to the pytest plugin how-to, with a runnable example the docs suite executes - Note the marker parses under the pytest plugin (.rst, .md, .py) but not the standalone doctest_docutils CLI
tony
added a commit
to git-pull/gp-sphinx
that referenced
this pull request
Jul 14, 2026
…ier (#65) Two independent API-documentation polish changes. One hides incidental doctest setup from rendered autodoc output while the example still runs as a test; the other stops class-member modifiers from rendering twice. - **Hide `+HIDE` doctest setup** (`typehints-gp`): doctest lines tagged `# doctest: +HIDE` are dropped from the rendered docstring, along with their `...` continuations, so plumbing like an `env` mapping or a socket path executes without cluttering the example. The strip runs at Sphinx build time; the source docstring — and the test that runs from it — is untouched. - **Fix double-rendered modifiers** (`api-style`): members marked `classmethod`, `staticmethod`, `async`, or `abstract` showed the modifier twice — once as a signature prefix, once as the badge beside it. The redundant prefix is dropped so each modifier appears only in its badge; `property`/`type` word prefixes are left untouched. - **Documentation**: the `typehints-gp` how-to gains a "Hiding incidental doctest setup" section covering the flag and the doctest-runner registration it needs. See also: git-pull/gp-libs#79
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
1 participant
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.
What
Register a
HIDEdoctest optionflag so an example can be marked# doctest: +HIDE.HIDEis a no-op for execution — the output checker never consults it — but without registration,# doctest: +HIDEraisesValueError: ... invalid option: '+HIDE'at collection time.Registration is eager (in
pytest_configure, before collection), because the.pydocstring path delegates to pytest's ownDoctestModule, which never calls this plugin's_get_flag_lookup.Why
Documentation tooling (a Sphinx
autodoc-process-docstringhook in gp-sphinx) can then drop+HIDE-marked setup lines from rendered output while the doctest runner still executes them — the runner reads__doc__from source, untouched by the render strip. This lets a docstring run incidental plumbing (building anenvmapping, a socket path) without cluttering the reader-facing docs.Tests
test_hide_optionflag_py_docstring: a.pydocstring carrying# doctest: +HIDEcollects and runs as a no-op.Part of a coordinated set with gp-sphinx (the render-side strip) and a downstream consumer that adopts the marker.