Docstring coverage - python code documentation coverage

How to check that python-developers (or yourself) have well documented the code, except how to view everything with your hands or generate pydoc documentation and compare with the source? So I did not find any solution, until I accidentally came across an old-aged script that inspired me to fork and subsequent simple refinement.



As a result, I got a simple and useful (at least for me :) tool Docstring coverage, which allows to estimate the percentage of code coverage documentation for the entire project.





')

Runs like this:

docstring-coverage [] <    > 

Example output:

 $ docstring-coverage docstring-coverage/ File docstring-coverage/setup.py - No module dostring! Needed: 1; Exist: 0; Missing: 1; Coverage: 0.0% File docstring-coverage/docstringcoverage/__init__.py - No module dostring! Needed: 1; Exist: 0; Missing: 1; Coverage: 0.0% File docstring-coverage/docstringcoverage/cover.py - No docstring for DocStringCoverageVisitor! - No docstring for DocStringCoverageVisitor.__init__! - No docstring for DocStringCoverageVisitor.visitModule! - No docstring for DocStringCoverageVisitor.visitClass! - No docstring for DocStringCoverageVisitor.visitFunction! - No docstring for DocStringCoverageVisitor.getResult! - No docstring for get_docstring_coverage.printDocstring! Needed: 11; Exist: 4; Missing: 7; Coverage: 36.4% Overall statistics for 3 files: Docstrings needed: 13; Docstrings exist: 4; Docstrings missing: 9 Total docstring coverage: 30.8%; Grade: not so good 

Among the options are -m, which causes the utility to skip the __magic__ methods of python and -v, which allows you to adjust the output talkative level from 0 to 3.



If desired, you can import into the working draft to use to obtain statistics on coverage:

 import docstringcoverage cover_results = docstringcoverage.get_docstring_coverage(['somefolder/somefile.py']) 

Given as a list with two dict elements:

 [ {'< >': { 'missing': ["< ,   ","..."], 'module_doc': <True or False>, #     'missing_count': <missing_count>, #   'needed_count': <needed_docstrings_count>, #     'coverage': <percent_of_coverage>, #  'empty': <True or False> #True,    #( , ,   ) }, ... }, #   { 'missing_count': <total_missing_count>, 'needed_count': <total_needed_docstrings_count>, 'coverage': <total_percent_of_coverage>, } 

All documentation with examples is on the project page.