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

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

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

参考資料

• Sphinxサイト