Sourcecode on GitHub Sourcecode License Documentation Documentation License
PyPI PyPI - Status PyPI - Python Version
GitHub Workflow - Build and Test Status Libraries.io status for latest release Codacy - Quality Codacy - Coverage Codecov - Branch Coverage

Sphinx Reports

The Sphinx extension sphinx_reports offers a set of directives to integrate reports and summaries into the documentation generated by Sphinx.

Supported format reports are:

  • ✅🚧 Unit Test summaries (by pytest)
    • ✅ Summary page (displaying unittest.xml)
    • 🚧 Show logging, output and error messages.
  • 🚧 Code coverage (by Coverage.py)
    • ✅ Summary page (displaying coverage.json)
    • 🚧 Individual Sphinx documents per package/module
    • 🚧 Highlighted source code with syntax highlighting and coverage highlighting
  • 🚧 Documentation coverage
    • ✅ Summary page (displaying data from """docstr_coverage""")
    • ❓ Additionally support interrogate as data source.
    • 🚧 Individual Sphinx documents per package/module
    • 🚧 Highlighted source code with syntax highlighting and coverage highlighting
  • 🚧 Package Dependencies
    • 🚧 Summary page (displaying requirements.txt)

Extension Configuration

This README demonstrates a quick and minimal configuration for the Sphinx extension and it's provided directives. See the sphinx-reports documentation for more details.

At first, add the extension name to the list of extensions in conf.py, so the extension is loaded by Sphinx.

# Sphinx extensions
extensions = [
  # ...
  "sphinx_reports",
]

Each report directive might require an individual configuration, therefore see the next sections for details.

Unittest Report Summary

The Unittests Report collects the success or failure of unittests. The results are typically stored in an XML file, which can be read by sphinx-reports. After reading the structure of testsuites and testcases, the report can be visualized. The user

Unitest Summary Page

This is a quick and minimal configuration for the unittest summary directives. See the unittest documentation for more details.

Quick Configuration - Step-by-Step

  1. Configure one or more coverage analysis reports in conf.py by adding a new 'section' defining some configuration variables. Each unittest report is identified by an ID, which is later referred to by the report directive. Here, the ID is called src (dictionary key). Each unittest report needs 1 configuration entry:

    • xml_report - The unittest report as XML file as generated by pytest.
    report_unittest_testsuites = {
  "src": {
    "xml_report": "../report/unit/unittest.xml"
  }
}

  2. Add the unittest-summary directive into your Restructured Text (ReST) document.

    • reportid - The ID used in conf.py to describe a report.
    .. report:unittest-summary::
   :reportid: src

Code Coverage Summary

Code Coverage checks if a source code was used during execution. Usually, testcases are run by a testcase execution framework like pytest, which also offers to instrument the code for code coverage collection using the pytest-cov plugin. For Python, coverage collection is usually based on Coverage.py, which supports statement and branch coverage collection either as XML or JSON files. sphinx-reports can visualize a code coverage summary from JSON files.

Code Coverage Summary Page

This is a quick and minimal configuration for the code coverage directives. See the code coverage documentation for more details.

Quick Configuration - Step-by-Step

  1. Configure one or more coverage analysis reports in conf.py by adding a new 'section' defining some configuration variables. Each analysis report is identified by an ID, which is later referred to by the report directive. Here, the ID is called src (dictionary key). Each analysis report needs 4 configuration entries:

    • name - Name of the Python package1.
    • json_report - The code coverage report as JSON file as generated by Coverage.py.
    • fail_below - An integer value in range 0..100, for when a code coverage is considered FAILED.
    • levels - A predefined color pallet name or a dictionary of coverage limits, their description and CSS style classes.
    # ==============================================================================
# Sphinx-reports - CodeCov
# ==============================================================================
report_codecov_packages = {
  "src": {
    "name":        "myPackage",
    "json_report": "../report/coverage/coverage.json",
    "fail_below":  80,
    "levels":      "default"
  }
}

  2. Add the code-coverage directive into your Restructured Text (ReST) document.

    • reportid - The ID used in conf.py to describe a Python package.
    .. report:code-coverage::
   :reportid: src

Documentation Coverage Summary

Documentation Coverage counts how many publicly accessible members are documented using a Python doc-string. Based on the count of possibly documented public members and the actual number of non-empty doc-strings, a percentage of documentation coverage can be computed.

Documentation coverage is a measure of code quality, which expresses how well documented (completeness or documentation, but not necessarily quality/helpfulness of documentation) source code is. Well documented code helps to use and maintain the existing code base. It also allows for automated documentation generation.

Documentation Coverage Summary Page

This is a quick and minimal configuration for the documentation coverage directives. See the documentation coverage documentation for more details.

Quick Configuration - Step-by-Step

  1. Configure one or more Python packages for documentation coverage analysis in conf.py by adding a new 'section' defining some configuration variables. Each package is identified by an ID, which is later referred to by the report directive. Here, the ID is called src (dictionary key). Each package needs 4 configuration entries:

    • name - Name of the Python package1.
    • directory - The directory of the package to analyze.
    • fail_below - An integer value in range 0..100, for when a documentation coverage is considered FAILED.
    • levels - A predefined color pallet name or a dictionary of coverage limits, their description and CSS style classes.
    # ==============================================================================
# Sphinx-reports - DocCov
# ==============================================================================
report_doccov_packages = {
  "src": {
    "name":       "myPackage",
    "directory":  "../myPackage",
    "fail_below": 80,
    "levels":     "default"
  }
}

  2. Add the doc-coverage directive into your Restructured Text (ReST) document.

    • reportid - The ID used in conf.py to describe a Python package.
    .. report:doc-coverage::
   :reportid: src

Package Dependencies

🚧 In planning phase 🚧

Contributors

License

This Python package (source code) is licensed under Apache License 2.0.
The accompanying documentation is licensed under Creative Commons - Attribution-4.0 (CC-BY 4.0).

SPDX-License-Identifier: Apache-2.0

  1. Toplevel Python packages can reside in a directory not matching the package name. This is possible because the toplevel package name is set in the package installation description. This is not good practice, but possible and unfortunately widely used. E.g. src as directory name. ↩ ↩2

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for Paebbels from gravatar.com Paebbels

Credits

Author: Patrick Lehmann

License

Apache Software License (Apache-2.0)

Requires

Python >=3.12

Provides Extra

doc test all

Tags

Python3 Sphinx Extension Report doc-string interrogate Code Coverage Coverage Documentation Coverage Unittest Dependencies Summary

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinx_reports-0.11.2.tar.gz (36.6 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

sphinx_reports-0.11.2-py3-none-any.whl (47.5 kB view details)

Uploaded Python 3

File details

Details for the file sphinx_reports-0.11.2.tar.gz.

File metadata

  • Download URL: sphinx_reports-0.11.2.tar.gz
  • Upload date:
  • Size: 36.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.14.6

File hashes

Hashes for sphinx_reports-0.11.2.tar.gz
Algorithm Hash digest
SHA256 0d9bb5932651d63e791173220b068d33c303ce0c8e3d03c576b285980d0a0fa2
MD5 459781f750cfef8783fcb6a3b91d0e74
BLAKE2b-256 f56209412f1f63439435c05393db7e83260ca2cf0492be5a0c42c6323268afbc

See more details on using hashes here.

File details

Details for the file sphinx_reports-0.11.2-py3-none-any.whl.

File metadata

File hashes

Hashes for sphinx_reports-0.11.2-py3-none-any.whl
Algorithm Hash digest
SHA256 e761b325ed61b4f20c5da06ef76d22a00c1ec13d37f7b1529de3d07aa6f89e8d
MD5 89edb48348fc12bb2b34a1dad79d3874
BLAKE2b-256 148f25884b83102bb6f380967542a467147a84bc98a2580aa16adf5de9f77cf7

See more details on using hashes here.

Release history Release notifications | RSS feed

This release

0.11.2 This release

2 files

0.11.1

2 files

0.11.0

2 files

0.10.0

2 files

0.9.9

2 files

0.9.7

2 files

0.9.6

2 files

0.9.5

2 files

0.9.4

2 files

0.9.3

2 files

0.9.2

2 files

0.9.1

2 files

0.9.0

2 files

0.8.0

2 files

0.7.5

2 files

0.7.4

2 files

0.7.3

2 files

0.7.2

2 files

0.7.1

2 files

0.7.0

2 files

0.6.0

2 files

0.5.1

2 files

0.5.0

2 files

0.4.0

2 files

0.3.1

2 files

0.2.0

2 files

0.1.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page