{"id":23237405,"url":"https://github.com/pytooling/sphinx-reports","last_synced_at":"2025-06-10T19:11:24.026Z","repository":{"id":216198790,"uuid":"740149217","full_name":"pyTooling/sphinx-reports","owner":"pyTooling","description":"Integrate reports (code coverage, doc. coverage, pytest, mypy, ...) into Sphinx documentation as appendix pages.","archived":false,"fork":false,"pushed_at":"2025-06-05T05:44:44.000Z","size":7372,"stargazers_count":8,"open_issues_count":3,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-05T07:01:46.881Z","etag":null,"topics":["coverage-report","docstring","documentation","interrogate","pytest","pytest-cov","sphinx","sphinx-extension","unittest"],"latest_commit_sha":null,"homepage":"https://pytooling.github.io/sphinx-reports/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pyTooling.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-01-07T17:08:07.000Z","updated_at":"2025-06-05T05:24:10.000Z","dependencies_parsed_at":"2024-03-22T23:28:37.881Z","dependency_job_id":"0082a2eb-dcce-49aa-8634-a1f83cedb961","html_url":"https://github.com/pyTooling/sphinx-reports","commit_stats":null,"previous_names":["pytooling/sphinx-reports"],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyTooling%2Fsphinx-reports","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyTooling%2Fsphinx-reports/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyTooling%2Fsphinx-reports/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyTooling%2Fsphinx-reports/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pyTooling","download_url":"https://codeload.github.com/pyTooling/sphinx-reports/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyTooling%2Fsphinx-reports/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":258962526,"owners_count":22784832,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["coverage-report","docstring","documentation","interrogate","pytest","pytest-cov","sphinx","sphinx-extension","unittest"],"created_at":"2024-12-19T04:13:32.908Z","updated_at":"2025-06-10T19:11:24.012Z","avatar_url":"https://github.com/pyTooling.png","language":"Python","readme":"[![Sourcecode on GitHub](https://img.shields.io/badge/pyTooling-sphinx--reports-323131.svg?logo=github\u0026longCache=true)](https://github.com/pyTooling/sphinx-reports)\n[![Sourcecode License](https://img.shields.io/pypi/l/sphinx-reports?longCache=true\u0026style=flat-square\u0026logo=Apache\u0026label=code)](LICENSE.md)\n[![Documentation](https://img.shields.io/website?longCache=true\u0026style=flat-square\u0026label=pyTooling.github.io%2Fsphinx-reports\u0026logo=GitHub\u0026logoColor=fff\u0026up_color=blueviolet\u0026up_message=Read%20now%20%E2%9E%9A\u0026url=https%3A%2F%2FpyTooling.github.io%2Fsphinx%2Dreports%2Findex.html)](https://pyTooling.github.io/sphinx-reports/)\n[![Documentation License](https://img.shields.io/badge/doc-CC--BY%204.0-green?longCache=true\u0026style=flat-square\u0026logo=CreativeCommons\u0026logoColor=fff)](LICENSE.md)  \n[![PyPI](https://img.shields.io/pypi/v/sphinx-reports?longCache=true\u0026style=flat-square\u0026logo=PyPI\u0026logoColor=FBE072)](https://pypi.org/project/sphinx-reports/)\n![PyPI - Status](https://img.shields.io/pypi/status/sphinx-reports?longCache=true\u0026style=flat-square\u0026logo=PyPI\u0026logoColor=FBE072)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/sphinx-reports?longCache=true\u0026style=flat-square\u0026logo=PyPI\u0026logoColor=FBE072)  \n[![GitHub Workflow - Build and Test Status](https://img.shields.io/github/actions/workflow/status/pyTooling/sphinx-reports/Pipeline.yml?branch=main\u0026longCache=true\u0026style=flat-square\u0026label=build%20and%20test\u0026logo=GitHub%20Actions\u0026logoColor=FFFFFF)](https://GitHub.com/pyTooling/sphinx-reports/actions/workflows/Pipeline.yml)\n[![Libraries.io status for latest release](https://img.shields.io/librariesio/release/pypi/sphinx-reports?longCache=true\u0026style=flat-square\u0026logo=Libraries.io\u0026logoColor=fff)](https://libraries.io/github/pyTooling/sphinx-reports)\n[![Codacy - Quality](https://img.shields.io/codacy/grade/9a89bbc1d2c04a699ea14abea75588c7?longCache=true\u0026style=flat-square\u0026logo=Codacy)](https://www.codacy.com/gh/pyTooling/sphinx-reports)\n[![Codacy - Coverage](https://img.shields.io/codacy/coverage/9a89bbc1d2c04a699ea14abea75588c7?longCache=true\u0026style=flat-square\u0026logo=Codacy)](https://www.codacy.com/gh/pyTooling/sphinx-reports)\n[![Codecov - Branch Coverage](https://img.shields.io/codecov/c/github/pyTooling/sphinx-reports?longCache=true\u0026style=flat-square\u0026logo=Codecov)](https://codecov.io/gh/pyTooling/sphinx-reports)\n\n\n\u003c!--\n[![GitHub release date](https://img.shields.io/github/release-date/pyTooling/sphinx-reports?logo=GitHub\u0026)](https://github.com/pyTooling/sphinx-reports/releases)  \n[![Dependent repos (via libraries.io)](https://img.shields.io/librariesio/dependent-repos/pypi/sphinx-reports)](https://github.com/pyTooling/sphinx-reports/network/dependents)  \n--\u003e\n\n\n# Sphinx Reports\n\nThe Sphinx extension `sphinx_reports` offers a set of directives to integrate reports and summaries into the\ndocumentation generated by Sphinx.\n\nSupported format reports are:\n* ✅🚧 Unit Test summaries (by [pytest](https://github.com/pytest-dev/pytest))\n  * ✅ Summary page (displaying `unittest.xml`)\n  * 🚧 Show logging, output and error messages.\n* 🚧 Code coverage (by [Coverage.py](https://github.com/nedbat/coveragepy))\n  * ✅ Summary page (displaying `coverage.json`)\n  * 🚧 Individual Sphinx documents per package/module\n  * 🚧 Highlighted source code with syntax highlighting and coverage highlighting\n* 🚧 Documentation coverage\n  * ✅ Summary page (displaying data from [\"\"\"docstr_coverage\"\"\"](https://github.com/HunterMcGushion/docstr_coverage))\n  * ❓ Additionally support [interrogate](https://github.com/econchick/interrogate) as data source.\n  * 🚧 Individual Sphinx documents per package/module\n  * 🚧 Highlighted source code with syntax highlighting and coverage highlighting \n* 🚧 Package Dependencies\n  * 🚧 Summary page (displaying `requirements.txt`)\n\n\n## Extension Configuration\n\nThis README demonstrates a quick and minimal configuration for the Sphinx extension and it's provided directives. See\nthe [sphinx-reports documentation](https://pyTooling.github.io/sphinx-reports) for more details.\n\nAt first, add the extension name to the list of extensions in `conf.py`, so the extension is loaded by Sphinx.\n\n```Python\n# Sphinx extensions\nextensions = [\n  # ...\n  \"sphinx_reports\",\n]\n```\n\nEach report directive might require an individual configuration, therefore see the next sections for details.\n\n\n## Unittest Report Summary\n\nThe *Unittests Report* collects the success or failure of unittests. The results are typically stored in an XML file,\nwhich can be read by **sphinx-reports**. After reading the structure of testsuites and testcases, the report can be\nvisualized. The user  \n\n![Unitest Summary Page](doc/_static/Unittest.png)\n\n\nThis is a quick and minimal configuration for the *unittest summary* directives.\nSee the [unittest](https://pyTooling.github.io/sphinx-reports/Unittest/index.html) documentation for more details.\n\n\u003cdetails\u003e\u003csummary\u003eQuick Configuration - Step-by-Step\u003c/summary\u003e\n\n1. Configure one or more coverage analysis reports in `conf.py` by adding a new 'section' defining some configuration\n   variables. Each unittest report is identified by an ID, which is later referred to by the report directive. Here, the\n   ID is called ``src`` (dictionary key). Each unittest report needs 1 configuration entry:\n\n   * `xml_report` - The unittest report as XML file as generated by *pytest*.\n\n   ```Python\n   report_unittest_testsuites = {\n     \"src\": {\n       \"xml_report\": \"../report/unit/unittest.xml\"\n     }\n   }\n   ```\n2. Add the `unittest-summary` directive into your Restructured Text (ReST) document.\n\n   * `reportid` - The ID used in `conf.py` to describe a report.\n\n   ```ReST\n   .. report:unittest-summary::\n      :reportid: src\n   ```\n\n\u003c/details\u003e\n\n## Code Coverage Summary\n\n*Code Coverage* checks if a source code was used during execution. Usually, testcases are run by a testcase execution\nframework like [pytest](https://github.com/pytest-dev/pytest), which also offers to instrument the code for code\ncoverage collection using the `pytest-cov` plugin. For Python, coverage collection is usually based on\n[Coverage.py](https://github.com/nedbat/coveragepy\u003e), which supports statement and branch coverage collection either as\nXML or JSON files. **sphinx-reports** can visualize a code coverage summary from JSON files. \n\n![Code Coverage Summary Page](doc/_static/CodeCoverage.png)\n\n\nThis is a quick and minimal configuration for the *code coverage* directives.\nSee the [code coverage](https://pyTooling.github.io/sphinx-reports/CodeCov/index.html) documentation for more details.\n\n\u003cdetails\u003e\u003csummary\u003eQuick Configuration - Step-by-Step\u003c/summary\u003e\n\n1. Configure one or more coverage analysis reports in `conf.py` by adding a new 'section' defining some configuration\n   variables. Each analysis report is identified by an ID, which is later referred to by the report directive. Here, the\n   ID is called ``src`` (dictionary key). Each analysis report needs 4 configuration entries:\n\n   * `name` - Name of the Python package[^1].\n   * `json_report` - The code coverage report as JSON file as generated by *Coverage.py*.\n   * `fail_below` - An integer value in range 0..100, for when a code coverage is considered FAILED.\n   * `levels` - A predefined color pallet name or a dictionary of coverage limits, their description and CSS style classes.\n\n   ```Python\n   # ==============================================================================\n   # Sphinx-reports - CodeCov\n   # ==============================================================================\n   report_codecov_packages = {\n     \"src\": {\n       \"name\":        \"myPackage\",\n       \"json_report\": \"../report/coverage/coverage.json\",\n       \"fail_below\":  80,\n       \"levels\":      \"default\"\n     }\n   }\n   ```\n2. Add the `code-coverage` directive into your Restructured Text (ReST) document.\n\n   * `reportid` - The ID used in `conf.py` to describe a Python package.\n\n   ```ReST\n   .. report:code-coverage::\n      :reportid: src\n   ```\n\n\u003c/details\u003e\n\n\n## Documentation Coverage Summary\n\n*Documentation Coverage* counts how many publicly accessible members are documented using a Python *doc-string*. Based\non the count of possibly documented public members and the actual number of non-empty *doc-strings*, a percentage of\ndocumentation coverage can be computed.\n\nDocumentation coverage is a measure of code quality, which expresses how well documented (completeness or documentation,\nbut not necessarily quality/helpfulness of documentation) source code is. Well documented code helps to use and maintain\nthe existing code base. It also allows for automated documentation generation.\n\n![Documentation Coverage Summary Page](doc/_static/DocCoverage.png)\n\n\nThis is a quick and minimal configuration for the *documentation coverage* directives.\nSee the [documentation coverage](https://pyTooling.github.io/sphinx-reports/DocCov/index.html) documentation for more\ndetails.\n\n\u003cdetails\u003e\u003csummary\u003eQuick Configuration - Step-by-Step\u003c/summary\u003e\n\n1. Configure one or more Python packages for documentation coverage analysis in `conf.py` by adding a new 'section' \n   defining some configuration variables. Each package is identified by an ID, which is later referred to by the report\n   directive. Here, the ID is called `src` (dictionary key). Each package needs 4 configuration entries:\n\n   * `name` - Name of the Python package[^1].\n   * `directory` - The directory of the package to analyze.\n   * `fail_below` - An integer value in range 0..100, for when a documentation coverage is considered FAILED.\n   * `levels` - A predefined color pallet name or a dictionary of coverage limits, their description and CSS style classes.\n\n   ```Python\n   # ==============================================================================\n   # Sphinx-reports - DocCov\n   # ==============================================================================\n   report_doccov_packages = {\n     \"src\": {\n       \"name\":       \"myPackage\",\n       \"directory\":  \"../myPackage\",\n       \"fail_below\": 80,\n       \"levels\":     \"default\"\n     }\n   }\n   ```\n2. Add the `doc-coverage` directive into your Restructured Text (ReST) document.\n \n   * `reportid` - The ID used in `conf.py` to describe a Python package.\n\n   ```ReST\n   .. report:doc-coverage::\n      :reportid: src\n   ```\n\n\u003c/details\u003e\n\n\n## Package Dependencies\n\n🚧 In planning phase 🚧\n\n\n\n## Contributors\n\n* [Patrick Lehmann](https://github.com/Paebbels) (Maintainer)\n* [and more...](https://GitHub.com/pyTooling/sphinx-reports/graphs/contributors)\n\n\n## License\n\nThis Python package (source code) is licensed under [Apache License 2.0](LICENSE.md).  \nThe accompanying documentation is licensed under Creative Commons - Attribution-4.0 (CC-BY 4.0).\n\n\n-------------------------\n\nSPDX-License-Identifier: Apache-2.0\n\n\n[^1]: Toplevel Python packages can reside in a directory not matching the package name. This is possible because the\n      toplevel package name is set in the package installation description. This is not good practice, but possible and\n      unfortunately widely used. E.g. `src` as directory name.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpytooling%2Fsphinx-reports","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpytooling%2Fsphinx-reports","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpytooling%2Fsphinx-reports/lists"}