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

※記事内に商品プロモーションを含むことがあります。

はじめに

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

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

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

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

リンク

環境

OSはWindows 10とした。

Python v3.8.5
Sphinx v3.2.1

インストール

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

1

conda install sphinx

1

pip install sphinx

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

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

1

conda install sphinx_rtd_theme

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

Read the Docsテーマ
Jupyter Notebook documentation

Pythonスクリプトを用意する

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

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

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

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

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49


"""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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


"""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ファイルを生成する。

1

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

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

オプション	意味
-F	Sphinxプロジェクトをfullで生成する
-H	プロジェクト名を指定
-A	著者を指定
-V	プロジェクトのバージョンを指定
-o	出力先を指定

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

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

1

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行のコメントを外す。

1
2
3


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

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

1
2
3
4
5
6


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

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

1

html_theme = 'alabaster'

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

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

1

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

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

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

1

sphinx-build docs docs/_build

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

生成されたHTMLファイル

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

index.html

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

main.html