python書くなら絶対に使いたい2つのドキュメント生成ツール

python、djangoを本格的に勉強し始めて3ヶ月の自分からみて、これは便利だ！！！と思ったドキュメント生成ツールを2つ紹介します！
各ツールの概要 → djangoでの適用方法の順で記載しています。

検索してもよく上位に記載されている内容ですが、djangoでの適用例として参考いただければ幸いです。

## sphinxを使ったdocstringのドキュメンテーション

![sphinx](https://www.sphinx-doc.org/ja/master/_static/sphinxheader.png)

Sphinxは知的で美しいドキュメントを簡単に作れるようにするツールです。Georg Brandlによって開発され、BSDライセンスのもとで公開されています。
このツールはもともと、Python のドキュメンテーション用に作られました、今では幅広い言語のプロジェクトでドキュメント作成を容易にするツールとして利用されています。(by [公式サイト](https://www.sphinx-doc.org/ja/master/))

自分が知ったきっかけはRead the docsというオープンソースコミュニティのためのドキュメントホスティングサービスです。ちなみに、このサービスもDjangoで作られているそうです。

- [Read the docs 公式](https://readthedocs.org/)
- [jupyter notebookの例](https://jupyter-notebook.readthedocs.io/en/stable/)


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 入門](https://qiita.com/11ohina017/items/118b3b42b612e527dc1d)

ターミナルで以下のコマンドを実行します。

```bash
# ライブラリとテーマインストール
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 --------`を参考にしてみてください。

```python:conf.py

# -- 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](https://planset-study-sphinx.readthedocs.io/ja/latest/index.html#)
自分もrstで記述したリンク先が、django projectで使っているディレクトリ名とconflictしたため、rstを一部修正しました(・_・)

## coverageを使ったカバレッジレポート

お次はカバレッジレポートの生成です！完成イメージは → [コチラ](https://nedbatchelder.com/files/sample_coverage_html/index.html)
使用するツールはpytest、coverageの２つです！

![pytest](https://docs.pytest.org/en/stable/_static/pytest1.png)
公式: [pytest](https://docs.pytest.org/en/stable/)

pytest は、より良いプログラムを書くのに役立つ、成熟したフル機能の Python テストツールです。
pytest フレームワークを使用すると、小規模なテストを簡単に書くことができますが、アプリケーションやライブラリの複雑な機能テストをサポートするために拡張することができます。(by 公式)

pythonのテストフレームワークの１つです。
python標準のunittestというテストフレームワークがありますが、個人的にはpytestの方が比較演算子が直感的に書きやすいのが好みです。

![coverage](https://coverage.readthedocs.io/en/coverage-5.2.1/_static/sleepy-snake-circle-150.png)
公式: [coverage](https://coverage.readthedocs.io/en/coverage-5.2.1/)

Coverage.pyはPythonプログラムのコードカバレッジを測定するツールです。プログラムを監視し、コードのどの部分が実行されたかを記録し、ソースを分析して、実行された可能性があったが実行されなかったコードを特定します。
カバレッジの測定は通常、テストの有効性を評価するために使用されます。コードのどの部分がテストによって実行されていて、どの部分が実行されていないかを示すことができます。（by 公式）

テストしたコードの網羅性を確認するのに役立ちます。100％にすると満足感がありますが、まだまだ確認することはあるので要注意です。

coverageの機能の1つにreportのhtmlの出力の機能があります。

- テストした箇所がわかりやすい
- ドキュメント作成の手間を削減できる

と一石二鳥です！ぜひ使ってみてください！

### 作成手順

それでは、Django projectにおけるpytest,coverageの設定とレポートの出力を行っていきましょう！

ターミナルで以下のコマンドを実行します。

```bash
# ライブラリをインストール
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](https://pytest-django.readthedocs.io/en/latest/tutorial.html)も分量少なくわかりやすいのでチェックしてみてください。

```ini:pytest.ini
[pytest]
addopts = --ds=config.settings # django settingsを指定
python_files = tests.py test_*.py # テストコードを指定
```

* .coveragerc

coverageコマンドのrun、report、htmlのオプションを定義するファイルです。
こちらも公式[coverage](https://coverage.readthedocs.io/en/coverage-5.2.1/config.html)のオプション説明が分量もすくなくわかりやすいです。html出力の他にxml、json出力も可能です。

```ini:.coveragerc
[run]
source=. # django project rootを指定
omit= */migrations/*　# 対象外にしたいファイル、ディレクトリを記載
      */tests/*
      */htmlcov/*
[report]
omit= */migrations/*
      */tests/*
[html]
directory = htmlcov # htmlcovというディレクトリにhtmlを出力します
```

※htmlカバレッジも取りたい場合は`pip install django-coverage-plugin`を実行し以下を追記してください。

```ini:.coveragerc
[run]
plugins =
    django_coverage_plugin
```

参考：[Djangoメモ(26) : coverage.pyでカバレッジ（網羅率）を計測](https://wonderwall.hatenablog.com/entry/2018/03/26/003000)

こちらも簡単操作で、見やすいドキュメントが自動生成できます！
コマンドで行う場合は`coverage report -m`で網羅できていない行番号を確認したり、`pytest -v`でテストの詳細を表示したりするのがわかりやすいです。

## 最後に

少ない手間でドキュメントを作成できるので、使うのが許されるのであれば仕事効率も捗るのではないでしょうか。
今回はdjangoを例に上げましたが、djangoではなくても利用できるのでぜひ使ってみてください。
他にもおすすめのドキュメント自動作成ツールがありましたらコメントいただけると幸いです。

お読みいただきありがとうございました。