DEV Community

epassaro

Posted on Nov 19, 2021 • Edited on Nov 27, 2021

Measure docstring coverage of Python packages with GitHub Actions

#actionshackathon21

Workflows that enforce code style and coverage are widely used on GitHub, but... what about code documentation?

This workflow does the job by using the docstr-coverage package.

Fails when the docstring coverage is lower than the score of the base branch (on pull requests) or the previous commit (on push). Files that made the job fail are blamed.
Pushing changes to the main branch updates the current coverage of the project by creating a dynamic badge with through the shields.io endpoint.
It is possible to define the range of the badge color based on the coverage results.

Maintainer Must-Haves

Measure docstring coverage of Python packages with GitHub Actions

Copy .github/workflows/docstr-cov.yml and .docstr.yaml to your repository.
Tweak the configuration file following the package documentation.
Login to https://jsonbin.org and store the API key as a repository secret named JSONBIN_APIKEY.
The workflow will fail if the coverage is lower than the score of the base branch (on pull_request) or the previous commit (on push), and files that made the job fail will be blamed.
Pushing to main branch updates the current coverage of the project by updating a nice badge.
You can change the color range of the badge by tweaking the RANGE variable at the top of the workflow. For example, 50..75 means that coverage below 50 will display a red badge, and above 75 a green one.
Remember to add the badge to your README.md

Make changes to example/base.py and see the workflow…

An older version of this workflow is currently used by TARDIS-SN, a Montecarlo radiative transfer code that creates synthetic spectra for supernovae.