SphinxでPython docstringからドキュメントを自動生成する

はじめに

#

ドキュメント生成ツールSphinxを使って、Pythonスクリプトのクラスや関数のdocstringからHTMLドキュメントを自動生成する方法を解説する。

おおまかな手順は以下の通り。

1. Pythonスクリプトのdocstringに、クラスやメソッドの説明を書く
2. SphinxでreStructuredText (reST) 形式のソースファイルを生成する
3. SphinxでHTML形式のドキュメントを生成（ビルド）する

reSTはマークアップ言語の一種である。

環境

#

OSはWindows 10とした。

• Python v3.8.5
• Sphinx v3.2.1

インストール

#

condaまたはpipでインストールできる。

conda install sphinx

pip install sphinx

また、Sphinxには標準で10個のHTMLテーマが用意されている（以下リンク参照）。 HTML Theming — Sphinx documentation

テーマを追加することも可能。例えば、Jupyter Notebookのリファレンスで使われているテーマsphinx_rtd_theme (Read the Docs) を追加するには、以下を実行する。

conda install sphinx_rtd_theme

もちろん、pip install sphinx_rtd_themeでもインストール可能。

Pythonスクリプトを用意する

#

以下のフォルダを用意し、main.py, sub.pyという2つのスクリプトを作成する。

project/
└── src/
    ├── main.py
    └── sub.py

各スクリプトのdocstringに、モジュール、クラス、関数の説明を記述する。 docstringの記述方法は、以下の3つがある。

• reStructuredTextスタイル
• Googleスタイル
• NumPyスタイル

GoogleスタイルやNumPyスタイルで記述する場合は、Sphinxでドキュメントを作成するときに拡張機能を使う必要がある。

ここではGoogleスタイルとする。スクリプトの中身は以下の通り。

"""Module summary.

This is main.py.
"""
class MyClass:
    """Summary line.

    This is MyClass.
    """
    def sum_test(self, x, y):
        """sum 2 values.

        Args:
            x (float): 1st argument
            y (float): 2nd argument

        Returns:
            float: summation

        Examples:
            関数の使い方

            >>> print(sum_test(3.2, 5.3))
            8.5
        """
        return x + y

class MyClass2:
    """Summary line.

    This is MyClass2.
    """
    def sum_test2(self, x, y):
        """sum 2 values.

        Args:
            x (float): 1st argument
            y (float): 2nd argument

        Returns:
            float: summation

        Examples:
            関数の使い方

            >>> print(sum_test2(3.2, 5.3))
            8.5
        """
        return x + y

"""Module summary.

This is sub.py.
"""
class MyClass2:
    """Summary line.

    This is MyClass2.
    """
    def sum_test2(self, x, y):
        """sum 2 values.

        Args:
            x (float): 1st argument
            y (float): 2nd argument

        Returns:
            float: summation

        Examples:
            関数の使い方

            >>> print(sum_test2(3.2, 5.3))
            8.5
        """
        return x + y

reSTファイルの生成

#

カレントディレクトリをprojectフォルダとして、sphinx-apidocコマンドを実行し、reSTファイルを生成する。

sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH>

<MODULE_PATH>はPythonスクリプトがあるフォルダである。 主なオプションは以下の通り。

その他のオプションは以下を参照。 sphinx-apidoc — Sphinx documentation

ここでは、以下を実行する。

sphinx-apidoc -F -H project -A Helve -V v1.0 -o docs src

実行すると、projectフォルダの下にdocsフォルダが作成され、さらにその下に3個の空フォルダと6個のファイルが生成される。

project/
├── src/
│   ├── main.py
│   └── sub.py
└── docs/
    ├── _build/
    ├── _static/
    ├── _templates/
    ├── conf.py
    ├── index.rst
    ├── main.rst
    ├── make.bat
    ├── Makefile
    └── sub.rst

conf.pyの編集

#

生成されたconf.pyを開き、2箇所編集する。 まず、以下の3行のコメントを外す。

import os
import sys
sys.path.insert(0, '（略）\\project\\src')

次に、拡張機能 (extensions) に'sphinx.ext.napoleon'を追加する。これは、GoogleスタイルやNumpyスタイルでdocstringを記述した場合に必要である。

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.viewcode',
    'sphinx.ext.todo',
    'sphinx.ext.napoleon'
]

ちなみに、HTMLのテーマを変更したい場合は、html_themeを変更する。

html_theme = 'alabaster'

HTML形式のドキュメントを生成

#

HTML形式のドキュメントを生成するには、sphinx-buildコマンドを実行する（カレントディレクトリはprojectフォルダのままとする）。

sphinx-build [options] <sourcedir> <outputdir> [filenames ...]

<sourcedir>はconf.pyがあるフォルダである（今回はdocs）。 <outputdir>はHTMLファイルの出力先である。どこでも良いが、今回は自動生成されたdocs/_buildフォルダとする。

よって、ここでは以下を実行する。

sphinx-build docs docs/_build

実行すると結果が20行程度に渡って表示されるが、build succeeded.と表示されたら成功である。

生成されたHTMLファイル

#

docs/_buildフォルダにHTMLファイルが生成されている。 index.htmlはトップページであり、モジュールの一覧が表示される。

個別のスクリプトのドキュメントは、同じ名前のHTMLファイルとなる(以下はmain.html)。モジュール、クラス、メソッドの説明が整形されて表示されている。

参考

#

• Sphinxの使い方．docstringを読み込んで仕様書を生成 - Qiita
• sphinx入門 その1 ドキュメントの自動生成 Python学習講座
• GoogleスタイルのPython Docstringの入門 - Qiita