feat: Add doc-pytest-plugin directive for pytest plugin docs#8
Merged
Conversation
tony
force-pushed
the
doc-pytest-plugin-gp-sphinx
branch
from
173ea3c to
a2c98d4
Compare
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #8 +/- ##
==========================================
+ Coverage 88.42% 88.59% +0.16%
==========================================
Files 71 71
Lines 6802 6955 +153
==========================================
+ Hits 6015 6162 +147
- Misses 787 793 +6 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
why: Downstream projects need a reusable way to publish pytest plugin pages with install guidance, autodetection notes, and generated fixture reference. what: - add doc-pytest-plugin to sphinx-autodoc-pytest-fixtures - cover page/reference modes and no-fixture warnings in integration tests - document the new helper in the package docs and README
tony
force-pushed
the
doc-pytest-plugin-gp-sphinx
branch
from
a2c98d4 to
cd48069
Compare
…on_nodes why: _build_doc_pytest_plugin_index_node was removed but the call site was not updated, crashing every docs build that uses doc-pytest-plugin. what: - Inline autofixture_index_node() construction with required ["module"] and ["exclude"] attributes - No new imports needed; autofixture_index_node already imported at line 41
…ptions why: mode: reference duplicates the manual recipe inside the helper, undermining the abstraction. :summary: multi-line values cause RST parse warnings. :project: is redundant when it equals 📦. what: - Remove mode from option_spec; intro block now always emits - Make :summary: optional with guard in _build_page_intro_nodes - Make :project: optional; empty string -> generic "test suite" link text (not package slug default) - Fix docs demo from eval-rst + mode: reference to native MyST colon-fence - Delete test_doc_pytest_plugin_reference_mode (tests removed behavior) - Update class docstring
…st-plugin API why: New optional :project: and :summary: options and removed :mode: need dedicated tests to prevent regressions. what: - test_doc_pytest_plugin_project_defaults_to_generic_link: :project: absent -> "test suite" generic text - test_doc_pytest_plugin_summary_optional: no :summary: -> no empty <p>, page still renders - test_doc_pytest_plugin_missing_package_fails_build: 📦 absent -> self.error() fires
why: Users need to know when to graduate from the directive to the manual recipe without discovering it by accident. what: - Add "When to use doc-pytest-plugin" section - Add "Manual recipe (power path)" section with concrete example
…n eval-rst
why: Two categories of warning were failing docs CI under sphinx-build -W.
(1) _is_markdown_source checked the outer file's .md extension, returning
True even for directives inside {eval-rst} blocks. Those directives use a
docutils RST Body state whose nested_parse is pure RST — passing a
{eval-rst} backtick fence to it caused spurious "Inline literal
start-string without end-string" and "Unexpected indentation" warnings.
The correct check is whether the directive was invoked natively by MyST,
which is detectable via isinstance(directive.state, MockState).
(2) The demo page documented spf_demo_fixtures twice (autofixtures:: block
+ doc-pytest-plugin section) without :no-index: on either, triggering 9
"duplicate object description" warnings.
what:
- Replace _is_markdown_source with _is_native_myst (MockState isinstance
check); eval-rst-embedded directives now skip the {eval-rst} wrap
- Add no_index parameter to _render_autofixtures_nodes to emit :no-index:
on each generated autofixture directive when requested
- Add "no-index" flag option to AutofixturesDirective; pass it through to
_render_autofixtures_nodes
- Add :no-index: to the demo autofixtures:: spf_demo_fixtures eval-rst
block so doc-pytest-plugin remains the canonical fixture reference
- Document :no-index: option in the autofixtures options table
…est-fixtures why: The CHANGES workspace package entry for sphinx-autodoc-pytest-fixtures only described the initial release; the new doc-pytest-plugin directive shipped on this branch needs a release note. what: - Add doc-pytest-plugin summary to sphinx-autodoc-pytest-fixtures entry
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.
Summary
Adds a higher-level
doc-pytest-plugindirective tosphinx-autodoc-pytest-fixturesfor building fixture-centric pytest plugin documentation pages.What changed
doc-pytest-plugindirective and documents it in the package README and docsautofixturecontent render correctly in both.rstand MyST Markdown pagesautofixturesanddoc-pytest-pluginTest plan
just ruffjust mypyjust testjust build-docs