Overview

The sphinx-reports extension provides a new domain called report, which adds new RestructuredText directives and roles.

These are described in the following categories:

• ✅ Unit Test Summary

• ✅ Code Coverage Report

• ✅ Documentation Coverage Report

• 🚧 Dependencies

General Extension Setup

To use the sphinx-reports extension in your Sphinx documentation project, the sphinx_reports package needs be downloaded and installed from PyPI in your environment. Sphinx-reports’s installation page also shows how to update the package from PyPI using pip.

At next, it’s recommended to add sphinx_reports to your documentation’s doc/requirements.txt. As updates and modifications to the sphinx_reports package might introduce braking changes, it’s recommended to specify a package version (range/limit). Usually, the major version number is fixed, because according to SemVer.org a breaking change needs to increment the major version number.

See the following doc/requirements.txt file as an example with commonly used extensions:

doc/requirements.txt

-r ../requirements.txt

# Enforce latest version on ReadTheDocs
sphinx ~= 8.2
docutils ~= 0.21

# ReadTheDocs Theme
sphinx_rtd_theme ~= 3.0

# Sphinx Extenstions
sphinxcontrib-mermaid ~= 1.0
autoapi ~= 2.0.1
sphinx_design ~= 0.6.1
sphinx-copybutton ~= 0.5.2
sphinx_autodoc_typehints ~= 3.2
sphinx_reports ~= 1.0             # <= new entry

Finally, the extension needs to be enabled in Sphinx’s conf.py, so the extension is loaded by Sphinx.

The following code snippets shows a list of commonly enabled extensions, including sphinx_report:

conf.py

# ==============================================================================
# Extensions
# ==============================================================================
extensions = [
# Standard Sphinx extensions
  "sphinx.ext.autodoc",
  "sphinx.ext.extlinks",
  "sphinx.ext.intersphinx",
  "sphinx.ext.inheritance_diagram",
  "sphinx.ext.todo",
  "sphinx.ext.graphviz",
  "sphinx.ext.mathjax",
  "sphinx.ext.ifconfig",
  "sphinx.ext.viewcode",
# SphinxContrib extensions
  "sphinxcontrib.mermaid",
# Other extensions
  "autoapi.sphinx",
  "sphinx_design",
  "sphinx_copybutton",
  "sphinx_autodoc_typehints",
  "sphinx_reports",             # <= new entry
# User defined extensions
  # ...
]