docstr-coverage badge

[fabiosangregorio]

📋 Description

docstr-coverage is a python package to get the documentation coverage for python projects.
This badge would show the total documentation coverage for the project (e.g. "docstr-coverage | 78% ") with a color gradient ranging from red to green based on the percentage.

🔗 Data
This badge will use a Github CI Artifact as its data.
It will get the data from a Github CI artifact through the Github APIs V3 (json, not GraphQL, because the needed APIs are not supported yet in GraphQL).

The user will need to run docstr-coverage in a Github Workflow and upload the result as a build artifact on Github. A sample Workflow file can be found below

Github Workflow file

name: docs

on:
  [push]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@master

    - name: Run documentation coverage
      run: |
        mkdir documentation-reports
        docstr-coverage telereddit --percentage-only 2>&1 | tee ./documentation-reports/docstr-coverage.txt
        
    - name: Upload documentation reports as artifact
      uses: actions/upload-artifact@v2
      with:
        name: documentation-reports
        path: ./documentation-reports/

The badge will:

• Get the artifacts list from the latest successful Github Workflow run (Link to the sample API)
• Get the single artifact download URL from last call (Link to the sample API)
• Download the zipped artifact and extract it
• Read the percentage from the coverage report and return it

🎤 Motivation
docstr-coverage is a relatively small package so it doesn't offer a full online service from which to fetch the coverage data. This badge would provide a "serviceless" way to surface data to shields through artifacts, and could also be used for future badges.