Pythonソースコードからドキュメント自動生成方法

Pythonソースコードからドキュメントを自動生成するツールに *Sphinx* というツールがあります。ソースコードにコメントを記述しておくと、このコメントの情報から美しいドキュメントを生成してくれます。
慣れが必要なので簡単に使い方を書きます。

# サンプル環境構築
* 仮想環境構築
```
$ python3 -m venv samplevenv
$ source samplevenv/bin/activate
$ git clone https://github.com/shunsvineyard/python-sample-code.git
$ cd python-sample-code
$ python3 -m pip install -r requirements.txt
$ rm -r docs
```

* ディレクトリ構成
```
├── LICENSE
├── README.rst
├── requirements.txt
├── setup.py
├── tests
└── trees
    ├── __init__.py
    ├── __main__.py
    ├── bin
    │   ├── __init__.py
    │   └── tree_cli.py
    ├── binary_trees
    │   ├── __init__.py
    │   ├── avl_tree.py
    │   ├── binary_search_tree.py
    │   ├── binary_tree.py
    │   ├── red_black_tree.py
    │   ├── threaded_binary_tree.py
    │   └── traversal.py
    └── tree_exceptions.py
```

* Sphinxソースディレクトリ作成
```
$ mkdir docs
$ cd docs
$ sphinx-quickstart
```
下記のようにいくつか問合せがくるので回答します。
```
Sphinx 4.5.0 クイックスタートユーティリティへようこそ。

以下の設定値を入力してください（Enter キーのみ押した場合、
かっこで囲まれた値をデフォルト値として受け入れます）。

選択されたルートパス: .

Sphinx 出力用のビルドディレクトリを配置する方法は2つあります。
ルートパス内にある "_build" ディレクトリを使うか、
ルートパス内に "source" と "build" ディレクトリを分ける方法です。
> ソースディレクトリとビルドディレクトリを分ける（y / n） [n]: y

プロジェクト名は、ビルドされたドキュメントのいくつかの場所にあります。
> プロジェクト名: AakelTechnologies
> 著者名（複数可）: AakelTechnologies
> プロジェクトのリリース []: 0.0.1

ドキュメントを英語以外の言語で書く場合は、
 言語コードで言語を選択できます。Sphinx は生成したテキストをその言語に翻訳します。

サポートされているコードのリストについては、
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language を参照してください。
> プロジェクトの言語 [en]: 
```

デフォルトのドキュメント作成(html形式)
```
$ make html
```

ドキュメントが
build/html/index.html
に出力されます。表示してみます。
```
$ open build/html/index.html
```
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1954348/9c40846e-c69c-0e12-82b5-9a296a1aa0b9.png)

sphinx-quickstartで生成されるディレクトリ構成
```
docs
├── Makefile
├── build
├── make.bat
└── source
    ├── _static
    ├── _templates
    ├── conf.py
    └── index.rst
```

サンプルプロジェクトディレクトリへのパスを設定する。
config.py内の下図をコメントアウトを外して編集する。
```
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
```
config.pyファイル自体のディレクトリ階層を基準に2つ上の階層（サンプルプロジェクトのトップ階層）を設定する。
```
import os
import sys
sys.path.insert(0, os.path.abspath('../..'))
```

同じくconfig.pyファイルに下図のコードが書かれているので、ここでエクステンションを設定する。NumpyやGoogleスタイルのdocstringsに対応させることができる。
```
extensions = [
]
```

編集後
```
extensions = [
    'sphinx.ext.napoleon'
]
```

PythonソースコードからreStructuredTextファイルを生成する。
```
sphinx-apidoc -f -o source/ ../trees/
```

sphinx-apidoc実行後のディレクトリ構成
```
docs
├── Makefile
├── build
│   └── doctrees
│       ├── environment.pickle
│       └── index.doctree
├── make.bat
└── source
    ├── _static
    ├── _templates
    ├── conf.py
    ├── index.rst
    ├── modules.rst
    ├── trees.bin.rst
    ├── trees.binary_trees.rst
    └── trees.rst
```

sphinx-apidoc実行で生成されたmodules.rstをindex.rstに追加してみる。
index.rstの下図の行を編集する。
```
.. toctree::
   :maxdepth: 2
   :caption: Contents:
```

編集後(.rstは書かない)
```
.. toctree::
   :maxdepth: 2
   :caption: Contents:

   modules
```

ドキュメントを生成
```
$ make html
```

build/html/index.htmlが生成されるので表示してみる。
```
$ open build/html/index.html
```

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1954348/35f9b0e9-5054-4622-6cd3-6b660ed9649f.png)

Contents項目に先ほどindex.rstに追加したmodulesの内容が反映される。
treesのリンクを辿っていけばより詳細の情報を参照できます。
このような形で実際のプロジェクトに適用していけば最新版のソースコードに同期したドキュメントを生成することができます。

# 参考資料
* [Sphinxサイト](https://www.sphinx-doc.org/en/master/index.html#)