Using interrogate as Sphinx extension

[Paebbels]

I have made a prototype to integrate documentation coverage results directly into a Sphinx documentation.

Are you interested in a cooperation?
Could you support this?

Source: https://pytooling.github.io/sphinx-reports/DocCoverage.html

---

Similar reports I can generate are:

• unit testing results: https://pytooling.github.io/sphinx-reports/unittests/index.html
• code coverage summary: https://pytooling.github.io/sphinx-reports/coverage/index.html

[econchick]

Interesting - is this essentially just like HTML support, like how coverage report can generate? How are you imagining this integrating into interrogate?

[Paebbels]

(Sorry I just noticed, I never updated the post with updated links to my prototype.
Now I added links to https://pytooling.github.io/sphinx-reports/)

---

The integration is different from coverage report or coverage html, when you refer to Coverage.py.
These commands generate:

• report → a coverage report on console,
• json → a coverage report converted to JSON,
• xml → a coverage report converted to XML,
• html → a coverage report rendered as HTML pages.

When it comes to code coverage (statement coverage and branch coverage), I can read XML and/or JSON files. See this page: https://pytooling.github.io/sphinx-reports/CodeCoverage.html for a demonstration.

Besides this I can also read and render unit test results. See https://pytooling.github.io/sphinx-reports/unittests/index.html for a demonstration.

---

But lets stay with documentation coverage, as this is the topic of interrogate. The current results are visible here: https://pytooling.github.io/sphinx-reports/DocCoverage.html

Currently, I use """docstr-coverage""" as a backend, but the code is written in a way that I could support other backends too. The usage is explained here: https://pytooling.github.io/sphinx-reports/DocCov/index.html
Essentially:

1. Define Python packages to investigate.
2. Refer to this package by an ID in a ReST directive.
   (This allows for multiple source directories or packages to be referenced individually by the ReST documentation.)

Are you interested?

---

How to integrate it?

So it's not that interrogate creates some outputs, it's the other ways around, I import interrogate and need an API to hand over files/directories for analysis and I get a data structure containing the coverage statistics.

I can convert from your data model to my data model, but I would prefer if we can find a common ground. Besides writing such Sphinx plugins, I spend some time in writing unified data models for libraries I need to fulfill my final goals (EDA²). That's why I have created a generalized data model for Code Coverage for Python code and I would like to generalize it further for any programming language (future work).

We can discuss pros and con of my data model, what parts are maybe missing for interrogate, etc. Such a process of a data model adaption (if wished) can also be an incremental path.

In future I would be interested in some kind of rules or settings to enforce or exclude certain objects from coverage counting. E.g. do nested function need a documentation? User should be able to tune the results.

What advantages are given by Sphinx?

1. The documentation coverage report can be an appendix to the documentation (handwritten + auto generated parts) and strengthen the quality of an open-source Python package.
2. The report is generated in Sphinx intermediate documentation representation form an can be converted to any output format.

What are future plans?

Have a per file (module) coloring of Python language constructs (variable, class, function, method, ...) colored with green, red, ... background (similar to Coverage.py HTML reports for used/unused code).

[Paebbels]

Ping.
Any updates from your side?

Update from my side:

Levels and colors can be customized via conf.py and CSS. The legend is a separate directive. I use Sphinx-Design with a grid to show them side-by-side.