みんなのdocstring書くモチベーションをあげるために、docstringの網羅率を計算して Pull Requestごとにdocstringの網羅率(coverage)の変化を表示したいな〜と思って調べたんですが、 そういった網羅率を計算するライブラリが見つけられなかったので、自分で作りました。
インストールの仕方と使い方を紹介します。
インストール
pip install doc-cov
これでdoccovコマンドが使えるようになります。
使い方
基本的には計算したいプロジェクトのパスを指定するだけ。 デフォルトではpublicな関数のdocstringの網羅率が出力されます。
$ doccov tests/sample_project
function 3 / 5 60.00%
Options
細かいオプションはREADMEにありますが、 いくつか例を出しておきます。
csv出力
$ doccov tests/sample_project --output csv
coverage,function,3,5,60.00%
関数だけでなくクラス・モジュールのcoverageも出力
doccov tests/sample_project -fmc
class 2 / 2 100.00% module 3 / 7 42.86% function 3 / 5 60.00%
モジュールごとにドキュメント網羅率を表示
$ doccov tests/sample_project --all
============================= module_fulldoc ----------------------------- function 1 / 1 100.00% ============================= package_A ----------------------------- function 0 / 0 - ============================= package_A.module_fulldoc ----------------------------- function 1 / 1 100.00% ============================= package_B ----------------------------- function 0 / 0 - ============================= package_B.module_shortdoc ----------------------------- function 1 / 1 100.00% ============================= package_B.package_B_1 ----------------------------- function 0 / 0 - ============================= package_B.package_B_1.module_nodoc ----------------------------- function 0 / 2 0.00% ============================= coverage ----------------------------- function 3 / 5 60.00%
pypi
pythonの標準で準備されているドキュメント生成モジュールのpydocの実装をごにょっとして作りました。会社や趣味のプロダクトのドキュメント網羅率を可視化してドキュメントモチベーションをあげるのに使ってください。
網羅率は計算できるようになったので、次はapiドキュメントをdocstringからいい感じに自動生成するやつを作ります〜。
