pythonドキュメントを自動作成

sphinxを使ったpythonドキュメントの自動作成手順に関するメモです。とりあえず「動いた」という状況でのまとめなのでご容赦を。
sphinxはpythonコード中に書き込んだコメントを自動的にhtmlに変換することができます。今回は下記のような複数ディレクトリのソースコードを共通のトップページにリンク及びリスト化されるような構成でドキュメントの自動化を試行します。

 - dirA
    - test.py
    - test2.py
 - dirB
    - testB.py
 - docs

docsは今回自動生成するドキュメントを格納する予定のディレクトリですので、初期は空です。

実行環境：Ubuntu18.04
Python：3.6

0. Pythonプログラムの用意

実験用に用意したpythonコードはそれぞれ、下記のようにソースコード内にコメントを記載しています。docstringという記法でコメントを記述しておくと、sphinx使用時にHTMLファイルに記述が自動的に追加されます。docstringの一つ、GoogleStyleなどを適宜参考に追記します。
https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html

class test():
    """test Class
    """

    def __init__(self):
        self.val = 0

    def SetVal(self, val):
       """SetVal function
       """
       self.val=val

    def GetVal(self):
        """GetVal function
        """
        return self.val

1. sphinxのインストール

$ sudo apt install python3-sphinx

2. サンプルMakefileを生成

2.1 sphinx-quickstartの実行

sphinx-quickstartコマンドで、htmlファイルをビルドするためのMakefileなど一式を、指定したディレクトリに生成してくれます。コマンドを実行するとインタラクティブに質問及び回答の入力が求められます。今回は下記だけ設定し、あとはデフォルトで実行します。

$sphinx-quickstart docs
...
ProjectName: sphinxTest
Auther name: hoge
Language: ja

上記実行後に、docs以下にいくつかのファイルとディレクトリが生成されます。次に、ドキュメントを生成する環境に合わせて生成されたファイルを編集します。

2.2 conf.pyの編集

20行目付近
サンプルのMakefileがあるディレクトリとターゲットとなるpythonコード群が確報されたディレクトリの相対位置関係をここで明記します。

import os
import sys
sys.path.insert(0, os.path.abspath('../dirA'))
sys.path.insert(0, os.path.abspath('../dirB'))

35行目付近
ドキュメント自動生成のためのオプションです。
詳細はhttp://www.sphinx-doc.org/ja/1.2/extensions.html

extensions = ["sphinx.ext.autodoc","sphinx.ext.autosummary"]

98行目付近
HTMLページのデザインを変更します。（任意）

html_theme = 'default'

3. Sphinx対応のドキュメントを自動生成

3.1 sphinx-apidocの実行

下記コマンドを実行し、2つのディレクトリに存在するコードのドキュメントを自動生成します。

$ sphinx-apidoc -f -o docs/dirA ./dirA
$ sphinx-apidoc -f -o docs/dirB ./dirB

上記コマンド実行後、docs以下に
dirA/modules.rst, test.rst, test2.srtが生成されます。
それぞれのファイルはreStructeredTextというフォーマットで記述されています。
詳細は下記ご参考。
https://www.sphinx-doc.org/ja/master/usage/restructuredtext/basics.html
modules.rstはshinx-apidoc実行時に自動生成されるファイルで、
対象のディレクトリ以下に存在するファイル一覧が自動的に生成されます。
例えば、今回は下記のような記述になっています。

dirA
====

.. toctree::
   :maxdepth: 4

   test
   test2

modules.rstはtest.rst、test2.rstを参照している、というツリー構造になっていることを意味します。

3.2 index.rstの編集

sphinx-quickstartを実行した際、./docs/index.rstというファイルが生成されています。ここをhtmlファイルのトップページとして使用します。index.rstから各ディレクトリのmodulesを参照しておけば、自動的に各ディレクトリのファイルがhtmlドキュメントに追加される仕組みになります。
ということで、./docs/index.rstを修正します。

Welcome to test's documentation!
================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   ./dirA/modules
   ./dirB/modules
＜以下省略＞

4. htmlファイルのビルド

最後にhtmlファイルをビルドします

$ sphinx-build -b html ./docs ./docs/_build/

これで、_build以下にhtmlファイルが自動生成されます。
./docs/_build/index.htmlをダブルクリックすると、
今回作成したファイルが下記のように出現します。

以上です。お疲れさまでした。

SphinxでPythonドキュメントの自動生成をしてみる