python、djangoを本格的に勉強し始めて3ヶ月の自分からみて、これは便利だ！！！と思ったドキュメント生成ツールを2つ紹介します！
各ツールの概要 → djangoでの適用方法の順で記載しています。
検索してもよく上位に記載されている内容ですが、djangoでの適用例として参考いただければ幸いです。
sphinxを使ったdocstringのドキュメンテーション
Sphinxは知的で美しいドキュメントを簡単に作れるようにするツールです。Georg Brandlによって開発され、BSDライセンスのもとで公開されています。
このツールはもともと、Python のドキュメンテーション用に作られました、今では幅広い言語のプロジェクトでドキュメント作成を容易にするツールとして利用されています。(by 公式サイト)
自分が知ったきっかけはRead the docsというオープンソースコミュニティのためのドキュメントホスティングサービスです。ちなみに、このサービスもDjangoで作られているそうです。
Sphinxでは reStructuredText と呼ばれるマークアップを利用する必要がありますがsphinx-apidocというコマンドでrstソースを自動生成することができます。
rstに変換する元の文章はdocstringを使用します。sphinx設定ファイルのconf.pyで記載されているsphinx.ext.autodocさんが元ディレクトリ下のdocstringを探してくれるようです。つまりは、
python docstring -> rst -> html
の変換をsphinxが全部やってくれるということです！圧倒的感謝！！
作成手順
早速django projectのドキュメントを作成していきましょう！
※事前にpython projectにdocstringを書いておく必要があります。
さっきから出てくるdocstringって何・・？って方はこちらの記事おすすめです → - Google docstring 入門
ターミナルで以下のコマンドを実行します。
# ライブラリとテーマインストール
pip install sphinx sphinx-rtd-theme
# ドキュメント出力先作成
mkdir docs
# django project rootを指定してrst作成
sphinx-apidoc -fF -o ./docs ./path/to/django_project_root
# change directory
cd docs
# conf.pyの調整(内容別途書いています！)
vi conf.py
# html作成
make html
- conf.py
追記部分のみ記載しています。
追記位置は# -- hogehoge --------を参考にしてみてください。
# -- Path setup --------------------------------------------------------------
# django projectへのパスとsettingsを指定
import os
import sys
sys.path.insert(0, os.path.abspath('path/to/django_project_root'))
import django
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'config.settings')
django.setup()
# -- General configuration ---------------------------------------------------
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.viewcode',
'sphinx.ext.todo',
'sphinx.ext.napoleon', # google, numpy styleのdocstring対応
]
language = 'ja' # あいあむじゃぱにーず
# -- Options for HTML output -------------------------------------------------
html_theme = 'sphinx_rtd_theme' # Read the Docsの見た目指定
あくまでも自動生成するだけなのですが、かなり完成度が高いです！
自動出力したrstを整えたい方はこの記事がとても参考になると思います → study sphinx
自分もrstで記述したリンク先が、django projectで使っているディレクトリ名とconflictしたため、rstを一部修正しました(・_・)
coverageを使ったカバレッジレポート
お次はカバレッジレポートの生成です！完成イメージは → コチラ
使用するツールはpytest、coverageの２つです！
公式: pytest
pytest は、より良いプログラムを書くのに役立つ、成熟したフル機能の Python テストツールです。
pytest フレームワークを使用すると、小規模なテストを簡単に書くことができますが、アプリケーションやライブラリの複雑な機能テストをサポートするために拡張することができます。(by 公式)
pythonのテストフレームワークの１つです。
python標準のunittestというテストフレームワークがありますが、個人的にはpytestの方が比較演算子が直感的に書きやすいのが好みです。
公式: coverage
Coverage.pyはPythonプログラムのコードカバレッジを測定するツールです。プログラムを監視し、コードのどの部分が実行されたかを記録し、ソースを分析して、実行された可能性があったが実行されなかったコードを特定します。
カバレッジの測定は通常、テストの有効性を評価するために使用されます。コードのどの部分がテストによって実行されていて、どの部分が実行されていないかを示すことができます。（by 公式）
テストしたコードの網羅性を確認するのに役立ちます。100％にすると満足感がありますが、まだまだ確認することはあるので要注意です。
coverageの機能の1つにreportのhtmlの出力の機能があります。
- テストした箇所がわかりやすい
- ドキュメント作成の手間を削減できる
と一石二鳥です！ぜひ使ってみてください！
作成手順
それでは、Django projectにおけるpytest,coverageの設定とレポートの出力を行っていきましょう！
ターミナルで以下のコマンドを実行します。
# ライブラリをインストール
pip install pytest-django coverage
# change directory(django projectのディレクトリ)
cd django_project_path
# pytest.iniの調整(内容別途書いています！)
vi pytest.ini
# p.coveragercの調整(内容別途書いています！)
vi .coveragerc
# coverageの取得
coverage run -m pytest
# coverage reportの確認
coverage report -m
# coverage htmlの出力
coverage html
- pytest.ini
今回は最低限の設定にしました。公式pytest-djangoも分量少なくわかりやすいのでチェックしてみてください。
[pytest]
addopts = --ds=config.settings # django settingsを指定
python_files = tests.py test_*.py # テストコードを指定
- .coveragerc
coverageコマンドのrun、report、htmlのオプションを定義するファイルです。
こちらも公式coverageのオプション説明が分量もすくなくわかりやすいです。html出力の他にxml、json出力も可能です。
[run]
source=. # django project rootを指定
omit= */migrations/* # 対象外にしたいファイル、ディレクトリを記載
*/tests/*
*/htmlcov/*
[report]
omit= */migrations/*
*/tests/*
[html]
directory = htmlcov # htmlcovというディレクトリにhtmlを出力します
※htmlカバレッジも取りたい場合はpip install django-coverage-pluginを実行し以下を追記してください。
[run]
plugins =
django_coverage_plugin
参考：Djangoメモ(26) : coverage.pyでカバレッジ（網羅率）を計測
こちらも簡単操作で、見やすいドキュメントが自動生成できます！
コマンドで行う場合はcoverage report -mで網羅できていない行番号を確認したり、pytest -vでテストの詳細を表示したりするのがわかりやすいです。
最後に
少ない手間でドキュメントを作成できるので、使うのが許されるのであれば仕事効率も捗るのではないでしょうか。
今回はdjangoを例に上げましたが、djangoではなくても利用できるのでぜひ使ってみてください。
他にもおすすめのドキュメント自動作成ツールがありましたらコメントいただけると幸いです。
お読みいただきありがとうございました。