conf.py

Overview

`conf.py` is the primary configuration file for the Sphinx documentation build system used by the **pytest** project. This file sets up all the necessary settings, extensions, and options to generate pytest's documentation in various output formats such as HTML, PDF, manual pages, EPUB, LaTeX, and Texinfo.

The file defines metadata about the project, configures Sphinx extensions for advanced documentation features, controls which files to include or exclude, and customizes output styling and indexing. It also includes runtime checks and conditional logic (for example, enabling certain extensions only if dependencies like Inkscape are available). Finally, it provides a `setup` function to extend Sphinx with pytest-specific cross-reference types, enabling richer linking and indexing in the documentation.

This configuration makes sure the documentation is consistent, well-structured, and integrates with pytest’s ecosystem and external references.

Detailed Explanation

Project Metadata

• project: The project name (pytest).

• copyright: The copyright notice.

• version: Major.minor.patch version extracted from pytest’s package version.

• release: Major.minor version string used for display in docs.

General Configuration

• root_doc: The root document for the documentation (index).

• extensions: List of Sphinx extensions used to enhance documentation features, including:

  • Syntax highlighting (pygments_pytest).

  • Autodoc and autosummary (automatic API docs).

  • Intersphinx (linking to other projects).

  • TODO notes, viewcode, towncrier drafts, GitHub issues references.

  • Conditional inclusion of sphinxcontrib.inkscapeconverter if Inkscape is installed.

• exclude_patterns: Patterns of files and directories excluded from the build, such as build directories, tests, old or attic directories, and specific RST files.

• templates_path: Directory for custom templates.

• default_role: Default interpreted text role in reStructuredText is set to literal.

• nitpicky: Enables warnings for broken references.

• nitpick_ignore: A list of known exceptions to ignore during nitpicky mode (mostly private or undocumented classes/objects).

Autodoc Configuration

• Controls the order of members (bysource), and how type hints are rendered (in descriptions).

Intersphinx Mapping

• Links to external documentation projects like pluggy, python, numpy, pip, tox, virtualenv, setuptools, and packaging.

TODO Extension

• Enables inclusion of TODO notes in the documentation.

Linkcheck Builder

• Configures link checking to ignore specific URLs and patterns.

• Sets the number of workers to parallelize link checking.

HTML Output Options

• Theme: furo with sidebar name hidden.

• Static paths and custom CSS file.

• Custom title, logo, favicon, and disables source links and index.

• Sets a base URL for the documentation.

Other Output Formats

Configuration sections for manual pages, EPUB, LaTeX, and Texinfo outputs with metadata and formatting options.

• LaTeX uses lualatex engine with a fallback font configuration for CJK characters and symbols.

• Texinfo documents authorship and project description.

Towncrier Draft Extension

• Controls changelog draft generation with autoversioning, including empty drafts.

• Defines working directory and config file path.

sphinx_issues Extension

• Configures GitHub repository path for issue/pr linking.

ReadTheDocs Environment Detection

• Detects if the build is a tagged release on RTD and sets a Sphinx tag accordingly (is_release).

setup Function

def setup(app: sphinx.application.Sphinx) -> None:
    ...

• Registers custom object types and cross-reference roles specific to pytest:

  • fixture — for built-in pytest fixtures.

  • confval — for configuration values.

  • globalvar — for global variables interpreted by pytest.

  • hook — for pytest hooks.

• Imports _pytest.legacypath to ensure references to pytest.Testdir (monkey-patched there) are discoverable by autodoc.

Usage Examples

While `conf.py` itself is not imported or called directly by users, its configuration affects how the documentation commands work.

Typical usage workflow:

# Build HTML docs:
sphinx-build -b html docs/ docs/_build/html

# Build PDF docs (requires LaTeX and Inkscape if SVG to PDF conversion is needed):
sphinx-build -b latex docs/ docs/_build/latex
make -C docs/_build/latex all-pdf

# Generate manual pages:
sphinx-build -b man docs/ docs/_build/man

The configuration ensures that:

• pytest-specific cross-references like :fixture: and :hook: are recognized.

• External references to pluggy, Python, numpy, etc., resolve correctly.

• Link checking ignores known problematic URLs.

• The documentation style and theme remain consistent across builds.

Important Implementation Details

• Uses shutil.which("inkscape") to detect whether to load the sphinxcontrib.inkscapeconverter extension, preventing warnings or build failures on systems without Inkscape.

• Defines nitpicky mode with a large ignore list to avoid warnings about private or undocumented pytest internals, third-party classes, and known issues.

• The setup function extends Sphinx’s domain model with pytest-specific roles to improve cross-referencing and indexing.

• Uses Path(__file__).parents[2].resolve() to establish the project root directory for relative paths (used in towncrier_draft configuration).

• Uses environment variables to detect ReadTheDocs build type and conditionally adds Sphinx tags, affecting conditional content inclusion.

Interactions with Other Parts of the System

• This configuration file interfaces directly with Sphinx’s build system and extensions.

• Reads version information from the pytest package (pytest.__version__).

• Imports _pytest.legacypath to enable autodoc references to patched test utilities.

• Integrates with external documentation projects via intersphinx.

• Enables towncrier changelog drafts by pointing to the project root and config file.

• Integrates GitHub issue/pr referencing via sphinx_issues.

• Controls CSS and static assets loaded into the HTML theme.

• Influences all generated documentation outputs (HTML, PDF, man pages, etc.).

Diagram: Structure of conf.py

flowchart TD
    A[conf.py]
    A --> B(Project Metadata)
    A --> C(General Configuration)
    A --> D(Extensions)
    D --> D1[pygments_pytest]
    D --> D2[sphinx.ext.autodoc]
    D --> D3[sphinx.ext.autosummary]
    D --> D4[sphinx.ext.intersphinx]
    D --> D5[sphinx.ext.todo]
    D --> D6[sphinx.ext.viewcode]
    D --> D7[sphinx_removed_in]
    D --> D8[sphinxcontrib_trio]
    D --> D9[sphinxcontrib.towncrier.ext]
    D --> D10[sphinx_issues]
    D --> D11[sphinxcontrib.inkscapeconverter (conditional)]
    A --> E(Output Options)
    E --> E1[HTML]
    E --> E2[PDF/LaTeX]
    E --> E3[Manual Pages]
    E --> E4[EPUB]
    E --> E5[Texinfo]
    A --> F(Linkcheck Configuration)
    A --> G(Intersphinx Mapping)
    A --> H(Towncrier Draft Configuration)
    A --> I(ReadTheDocs Environment Detection)
    A --> J[setup() function]
    J --> J1[Add Crossref Types: fixture, hook]
    J --> J2[Add Object Types: confval, globalvar]
    J --> J3[Import _pytest.legacypath]

Summary

`conf.py` is a critical configuration file that orchestrates the generation of pytest's comprehensive documentation. It sets project metadata, manages numerous Sphinx extensions, configures output formats, and customizes cross-referencing tailored to pytest’s domain. The file ensures smooth integration of external references, conditional extension loading, and enhanced documentation features, playing a central role in maintaining high-quality, user-friendly, and maintainable docs for the pytest project.