sphinx-autodoc-pytest-fixtures¶

Alpha GitHub PyPI

Sphinx extension for documenting pytest fixtures as first-class objects. It registers a Python-domain fixture directive and role, autodoc helpers for bulk fixture discovery, a higher-level pytest plugin page helper, and the badge/index UI used throughout the page below.

$ pip install sphinx-autodoc-pytest-fixtures

Downstream `conf.py`¶

extensions = ["sphinx_autodoc_pytest_fixtures"]

pytest_fixture_lint_level = "warning"
pytest_external_fixture_links = {
    "db": "https://docs.example.com/testing#db",
}

Registered configuration values¶

Config Value Index

Name	Type	Default	Rebuild
`pytest_fixture_hidden_dependencies`	`frozenset`	`frozenset({'cache', 'record_testsuite_property', 'capfd', 'recwarn', 'record_xml_attribute', 'capfdbinary', 'tmpdir', 'record_property', 'testdir', 'pytestconfig', 'capsysbinary', 'pytester'})`	`env`
`pytest_fixture_builtin_links`	`dict`	{'tmp_path_factory': 'https://docs.pytest.org/en/stable/reference/fixtures.html#tmp_path_factory', 'tmp_path': 'https://docs.pytest.org/en/stable/reference/fixtures.html#tmp_path', 'monkeypatch': 'https://docs.pytest.org/en/stable/reference/fixtures.html#monkeypatch', 'request': 'https://docs.pytest.org/en/stable/reference/fixtures.html#request', 'capsys': 'https://docs.pytest.org/en/stable/reference/fixtures.html#capsys', 'caplog': 'https://docs.pytest.org/en/stable/reference/fixtures.html#caplog'}	`env`
`pytest_external_fixture_links`	`dict`	`{}`	`env`
`pytest_fixture_lint_level`	`str`	`'warning'`	`env`

pytest_fixture_hidden_dependencies¶

Type:: frozenset

Fixture names to hide from dependency tracking

frozenset({'cache',
           'capfd',
           'capfdbinary',
           'capsysbinary',
           'pytestconfig',
           'pytester',
           'record_property',
           'record_testsuite_property',
           'record_xml_attribute',
           'recwarn',
           'testdir',
           'tmpdir'})

Registered by sphinx_autodoc_pytest_fixtures.setup().

Rebuild: env.

pytest_fixture_builtin_links¶

Type:: dict

Fallback URLs for pytest built-in fixtures

{'caplog': 'https://docs.pytest.org/en/stable/reference/fixtures.html#caplog',
 'capsys': 'https://docs.pytest.org/en/stable/reference/fixtures.html#capsys',
 'monkeypatch': 'https://docs.pytest.org/en/stable/reference/fixtures.html#monkeypatch',
 'request': 'https://docs.pytest.org/en/stable/reference/fixtures.html#request',
 'tmp_path': 'https://docs.pytest.org/en/stable/reference/fixtures.html#tmp_path',
 'tmp_path_factory': 'https://docs.pytest.org/en/stable/reference/fixtures.html#tmp_path_factory'}

Registered by sphinx_autodoc_pytest_fixtures.setup().

Rebuild: env.

pytest_external_fixture_links¶

Type:: dict
Default:: {}

Custom external fixture link URLs

Registered by sphinx_autodoc_pytest_fixtures.setup().

Rebuild: env.

pytest_fixture_lint_level¶

Type:: str
Default:: 'warning'

Validation severity: ‘none’, ‘warning’, or ‘error’

Registered by sphinx_autodoc_pytest_fixtures.setup().

Rebuild: env.

Registered directives and roles¶

Live demos¶

Fixture index¶

Fixture	Flags	Returns	Description
`demo_autouse`	auto fixture	`None`	Autouse fixture.
`demo_class`	class fixture	`str`	Class-scoped resource.
`demo_deprecated`	fixture	`str`	Return a value (deprecated since 1.0, replaced by demo_plain).
`demo_factory`	factory fixture	`type`[`str`]	Return a callable (factory kind).
`demo_module`	module fixture	`str`	Module-scoped resource.
`demo_override_hook`	fixture	`str`	Override hook — customise in conftest.py.
`demo_plain`	fixture	`str`	Plain function-scope resource.
`demo_session`	session fixture	`str`	Session-scoped resource.
`demo_session_autouse`	session auto fixture	`None`	Session-scoped autouse.
`demo_session_factory`	session factory fixture	`type`[`str`]	Session-scoped factory.

Bulk autodoc¶

fixture spf_demo_fixtures.demo_plain → strfixture: Plain function-scope resource. Shows FIXTURE badge only.

fixture spf_demo_fixtures.demo_session → strsession fixture: Session-scoped resource. Shows SESSION + FIXTURE badges.

Note

Created once per test session and shared across all tests. Requesting this fixture does not create a new instance per test.

fixture spf_demo_fixtures.demo_module → strmodule fixture: Module-scoped resource. Shows MODULE + FIXTURE badges.

fixture spf_demo_fixtures.demo_class → strclass fixture: Class-scoped resource. Shows CLASS + FIXTURE badges.

fixture spf_demo_fixtures.demo_factory → type[str]factory fixture

Return a callable (factory kind). Shows FACTORY + FIXTURE badges.

def test_example(demo_factory: type[str]) -> None:
    obj = demo_factory()
    assert obj is not None

fixture spf_demo_fixtures.demo_override_hook → strfixture: Override hook — customise in conftest.py. Shows OVERRIDE + FIXTURE badges.

fixture spf_demo_fixtures.demo_autouse → Noneauto fixture

Autouse fixture. Shows AUTO + FIXTURE badges.

Autouse:: yes — runs automatically for every test

Note

No request needed — this fixture runs automatically for every test.

fixture spf_demo_fixtures.demo_deprecated → strfixture

Return a value (deprecated since 1.0, replaced by demo_plain).

This fixture is documented with the deprecated RST option so the demo page can show the DEPRECATED + FIXTURE badge combination.

fixture spf_demo_fixtures.demo_session_factory → type[str]session factory fixture

Session-scoped factory. Shows SESSION + FACTORY + FIXTURE badges.

Note

Created once per test session and shared across all tests. Requesting this fixture does not create a new instance per test.

def test_example(demo_session_factory: type[str]) -> None:
    obj = demo_session_factory()
    assert obj is not None

fixture spf_demo_fixtures.demo_session_autouse → Nonesession auto fixture

Session-scoped autouse. Shows SESSION + AUTO + FIXTURE badges.

Note

Created once per test session and shared across all tests. Requesting this fixture does not create a new instance per test.

Autouse:: yes — runs automatically for every test

Note

No request needed — this fixture runs automatically for every test.

Plugin page helper¶

Install

$ pip install sphinx-autodoc-pytest-fixtures

Note

pytest auto-detects this plugin through the pytest11 entry point. Its fixtures are available without extra conftest.py imports.

Add project-specific usage notes here. The helper renders the install section, autodiscovery note, and full fixture summary/reference.

Fixture Summary

Fixture	Flags	Returns	Description
`demo_autouse`	auto fixture	`None`	Autouse fixture.
`demo_class`	class fixture	`str`	Class-scoped resource.
`demo_deprecated`	fixture	`str`	Return a value (deprecated since 1.0, replaced by demo_plain).
`demo_factory`	factory fixture	`type`[`str`]	Return a callable (factory kind).
`demo_module`	module fixture	`str`	Module-scoped resource.
`demo_override_hook`	fixture	`str`	Override hook — customise in conftest.py.
`demo_plain`	fixture	`str`	Plain function-scope resource.
`demo_session`	session fixture	`str`	Session-scoped resource.
`demo_session_autouse`	session auto fixture	`None`	Session-scoped autouse.
`demo_session_factory`	session factory fixture	`type`[`str`]	Session-scoped factory.

Fixture Reference

fixture spf_demo_fixtures.demo_plain → strfixture¶: Plain function-scope resource. Shows FIXTURE badge only.

fixture spf_demo_fixtures.demo_session → strsession fixture¶: Session-scoped resource. Shows SESSION + FIXTURE badges.

Note

Created once per test session and shared across all tests. Requesting this fixture does not create a new instance per test.

fixture spf_demo_fixtures.demo_module → strmodule fixture¶: Module-scoped resource. Shows MODULE + FIXTURE badges.

fixture spf_demo_fixtures.demo_class → strclass fixture¶: Class-scoped resource. Shows CLASS + FIXTURE badges.

fixture spf_demo_fixtures.demo_factory → type[str]factory fixture¶

Return a callable (factory kind). Shows FACTORY + FIXTURE badges.

def test_example(demo_factory: type[str]) -> None:
    obj = demo_factory()
    assert obj is not None

fixture spf_demo_fixtures.demo_override_hook → strfixture¶: Override hook — customise in conftest.py. Shows OVERRIDE + FIXTURE badges.

fixture spf_demo_fixtures.demo_autouse → Noneauto fixture¶

Autouse fixture. Shows AUTO + FIXTURE badges.

Autouse:: yes — runs automatically for every test

Note

No request needed — this fixture runs automatically for every test.

fixture spf_demo_fixtures.demo_deprecated → strfixture¶

Return a value (deprecated since 1.0, replaced by demo_plain).

This fixture is documented with the deprecated RST option so the demo page can show the DEPRECATED + FIXTURE badge combination.

fixture spf_demo_fixtures.demo_session_factory → type[str]session factory fixture¶

Session-scoped factory. Shows SESSION + FACTORY + FIXTURE badges.

Note

Created once per test session and shared across all tests. Requesting this fixture does not create a new instance per test.

def test_example(demo_session_factory: type[str]) -> None:
    obj = demo_session_factory()
    assert obj is not None

fixture spf_demo_fixtures.demo_session_autouse → Nonesession auto fixture¶

Session-scoped autouse. Shows SESSION + AUTO + FIXTURE badges.

Note

Created once per test session and shared across all tests. Requesting this fixture does not create a new instance per test.

Autouse:: yes — runs automatically for every test

Note

No request needed — this fixture runs automatically for every test.

When to use `doc-pytest-plugin`¶

Use this directive for a standard pytest plugin page where you want consistent house-style: an install section, the pytest11 autodiscovery note, and a generated fixture summary and reference.

Manual recipe (power path)¶

When you need custom layout — a different section order, content between the summary and reference, or no install block — use the low-level directives directly:

## Fixture Summary

```{autofixture-index} libvcs.pytest_plugin
```

## Fixture Reference

```{autofixtures} libvcs.pytest_plugin
```

autofixtures options¶

Option	Default	Description
`:order:`	`"source"`	`"source"` preserves module order; `"alpha"` sorts alphabetically
`:exclude:`	(empty)	Comma-separated fixture names to skip
`:no-index:`	(off)	Emit descriptions without registering fixtures in the domain index; use when the same module is documented twice on one page

autofixture-index options¶

Option	Default	Description
`:exclude:`	(empty)	Comma-separated fixture names to exclude from index

Single autodoc entries¶

fixture spf_demo_fixtures.demo_plain → strfixture: Plain function-scope resource. Shows FIXTURE badge only.

fixture spf_demo_fixtures.demo_session_factory → type[str]session factory fixture

Session-scoped factory. Shows SESSION + FACTORY + FIXTURE badges.

Note

Created once per test session and shared across all tests. Requesting this fixture does not create a new instance per test.

def test_example(demo_session_factory: type[str]) -> None:
    obj = demo_session_factory()
    assert obj is not None

Manual domain directive¶

fixture spf_demo_fixtures.demo_deprecateddeprecated fixture: Return a deprecated value. Use demo_plain instead.

Warning

Deprecated since version 1.0. Use demo_plain instead.

Copyable config snippet

extensions = [
    "sphinx_autodoc_pytest_fixtures",
]

Package metadata

Source on GitHub: sphinx-autodoc-pytest-fixtures
PyPI: sphinx-autodoc-pytest-fixtures
Maturity: Alpha

Registered Surface

sphinx_autodoc_pytest_fixtures

Config values

Name	Default	Rebuild	Types
`pytest_fixture_hidden_dependencies`	`frozenset({'cache', 'record_testsuite_property', 'capfd', 'recwarn', 'record_xml_attribute', 'capfdbinary', 'tmpdir', 'record_property', 'testdir', 'pytestconfig', 'capsysbinary', 'pytester'})`	`env`	`frozenset`
`pytest_fixture_builtin_links`	{'tmp_path_factory': 'https://docs.pytest.org/en/stable/reference/fixtures.html#tmp_path_factory', 'tmp_path': 'https://docs.pytest.org/en/stable/reference/fixtures.html#tmp_path', 'monkeypatch': 'https://docs.pytest.org/en/stable/reference/fixtures.html#monkeypatch', 'request': 'https://docs.pytest.org/en/stable/reference/fixtures.html#request', 'capsys': 'https://docs.pytest.org/en/stable/reference/fixtures.html#capsys', 'caplog': 'https://docs.pytest.org/en/stable/reference/fixtures.html#caplog'}	`env`	`dict`
`pytest_external_fixture_links`	`{}`	`env`	`dict`
`pytest_fixture_lint_level`	`'warning'`	`env`	`str`

Directives

Name	Kind	Callable	Summary
`std:fixture`	cross-reference directive	`add_crossref_type()`	Registers a standard-domain cross-reference target.
`py:fixture`	domain directive	`PyFixtureDirective`	Sphinx directive for documenting pytest fixtures: `.. py:fixture::`.
`autofixtures`	directive	`AutofixturesDirective`	Bulk fixture autodoc directive: `.. autofixtures:: module.name`.
`autofixture-index`	directive	`AutofixtureIndexDirective`	Generate a fixture index table from the :class:`FixtureStoreDict`.
`doc-pytest-plugin`	directive	`DocPytestPluginDirective`	Render a reusable pytest-plugin documentation page block.

py:fixture options

Option
`:annotation:`	Registered option
`:async:`	Registered option
`:autouse:`	Registered option
`:canonical:`	Registered option
`:depends:`	Registered option
`:deprecated:`	Registered option
`:factory:`	Registered option
`:kind:`	Registered option
`:module:`	Registered option
`:no-contents-entry:`	Registered option
`:no-index:`	Registered option
`:no-index-entry:`	Registered option
`:no-typesetting:`	Registered option
`:nocontentsentry:`	Registered option
`:noindex:`	Registered option
`:noindexentry:`	Registered option
`:overridable:`	Registered option
`:params:`	Registered option
`:replacement:`	Registered option
`:return-type:`	Registered option
`:scope:`	Registered option
`:single-line-parameter-list:`	Registered option
`:single-line-type-parameter-list:`	Registered option
`:teardown:`	Registered option
`:teardown-summary:`	Registered option
`:usage:`	Registered option

autofixtures options

Option
`:exclude:`	Registered option
`:no-index:`	Registered option
`:order:`	Registered option

autofixture-index options

Option
`:exclude:`	Registered option

doc-pytest-plugin options

Option
`:install-command:`	Registered option
`:package:`	Registered option
`:project:`	Registered option
`:summary:`	Registered option
`:tests-url:`	Registered option

Roles

Name	Kind	Callable	Summary
`std:fixture`	cross-reference role	`add_crossref_type()`	Registers a standard-domain cross-reference role.
`py:fixture`	domain role	`PyXRefRole`

Source on GitHub · PyPI

sphinx-autodoc-pytest-fixtures¶

Downstream conf.py¶

Registered configuration values¶

Registered directives and roles¶

Live demos¶

Fixture index¶

Bulk autodoc¶

Plugin page helper¶

When to use doc-pytest-plugin¶

Manual recipe (power path)¶

autofixtures options¶

autofixture-index options¶

Single autodoc entries¶

Manual domain directive¶

Downstream `conf.py`¶

When to use `doc-pytest-plugin`¶