Как проверить, что python-разработчики (или вы сами) хорошо задокументировали код, кроме как просматривать все руками или генерировать pydoc'ом документацию и сравнивать с исходниками? Вот и я не нашел никакого решения, пока случайно не натолкнулся на старый-престарый скрипт, который вдохновил меня на форк и последующую несложную доработку.
В результате у меня получился простой и полезный (по крайней мере для меня :) ) инструмент Docstring coverage, позволяющий оценить процентное покрытие кода документацией по всему проекту.
Запускается так:
docstring-coverage [опции] <путь к папке или модулю>Пример вывода:
$ 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%
<anchor>habracut</anchor>
Overall statistics for 3 files:
Docstrings needed: 13; Docstrings exist: 4; Docstrings missing: 9
Total docstring coverage: 30.8%; Grade: not so good
Среди опций есть -m, которая заставляет утилиту пропускать __магические__ методы python и -v, позволяющая настроить уровень «болтливости» вывода от 0 до 3.
При желании можно импортировать в рабочий проект использовать для получения статистики по покрытию:
import docstringcoverage
cover_results = docstringcoverage.get_docstring_coverage('somefolder/somefile.py')Отдается в виде списка с двумя элементами типа dict:
[
{'<имя файла>':
{
'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>,
}
Вся документация с примерами есть на странице проекта.
Автор: loststylus
