Python

SphinxでPythonのドキュメントを自動生成する手順

ここでは、Pythonコード内のドックストリングから自動的にHTMLドキュメントを生成することを想定しています。
ドックストリングの書き方については下記のページで解説しています。

Pythonのドックストリング(docstring)の書き方

前提条件

  • Pythonがインストール済みであること（Python 3.x系を推奨）。
  • コマンドラインでpython、pipなどの基本コマンドが使えること。

手順

仮想環境の作成（任意）

プロジェクトを管理しやすくするため、仮想環境（venv）を使うことをおすすめします。
（既に仮想環境を使っている場合、このステップは不要です）

python -m venv venv
source venv/bin/activate        # Linux/Mac
venv\Scripts\activate           # Windows

Sphinxのインストール

pipを使ってSphinxをインストールします。

pip install sphinx

ドキュメント用ディレクトリの作成

プロジェクトのルートディレクトリで、ドキュメント用のディレクトリ（例: docs）を作成します。

mkdir docs
cd docs

sphinx-quickstartを実行

docsディレクトリ内で以下を実行します。対話形式でドキュメントプロジェクトの初期設定が行われ、conf.pyやindex.rstなどの基本ファイルが生成されます。

sphinx-quickstart

主な質問事項と回答例:

  • Project name: (プロジェクト名を入力) 例: MyProject
  • Author name(s): (作者名)
  • Project release: (バージョン) 例: 1.0
  • Docstring: Separate source and build directoriesと聞かれた場合、yと答えるとsourceディレクトリとbuildディレクトリが分かれます。（初学者にはこちらを推奨）

ここで作られる主なファイルは以下の通りです:

  • conf.py: Sphinxの設定ファイル
  • index.rst: ドキュメントの目次ファイル

autodoc拡張の有効化（コードからドキュメントを生成する場合）

conf.pyを開き、extensionsリストに"sphinx.ext.autodoc"を追加します。

extensions = [
    'sphinx.ext.autodoc',
]

また、NumPyスタイルやGoogleスタイルのドックストリングを利用している場合は、対応する拡張機能（numpydocなど）を導入することもできます。

pip install numpydoc

そしてconf.pyにも追加:

extensions = [
    'sphinx.ext.autodoc',
    'numpydoc',
]

対象モジュールのパスを通す

conf.pyで、Sphinxがドキュメント化対象のPythonコードを読み込めるよう、プロジェクトのパスを設定します。例えば、sourceディレクトリ配下にソースコードがある場合:

import os
import sys
sys.path.insert(0, os.path.abspath('../..'))  # プロジェクトルートへのパスを追加

自分のプロジェクト構成に合わせてパスを修正してください。

rstファイルやautodoc指令を追加

index.rstや別の.rstファイルに、autodocディレクティブを使ってモジュールやクラス、関数をドキュメント化します。

.. automodule:: mymodule
   :members:

たとえばmymoduleというPythonモジュール（mymodule.py）がプロジェクト内にある場合、上記のような記述で、そのモジュール内のクラスや関数のドックストリングがドキュメント化されます。

index.rstからリンクを追加するなど、SphinxのreStructuredTextの基本的な書き方に慣れていくとよいでしょう。

ドキュメントのビルド

準備ができたら、docsディレクトリ（makefileがあるディレクトリ）で以下を実行します：

  • HTMLドキュメントの生成 make html

ビルドが完了すると、_build/htmlディレクトリ下にHTMLドキュメントが生成されます。index.htmlをブラウザで開くと確認できます。

ドキュメントの更新

コードやドックストリング、rstファイルを修正したら、再度make htmlを実行することで、更新されたドキュメントを再生成できます。

よくある質問・トラブルシューティング

自動ドキュメント生成でクラスや関数が表示されない場合

conf.pyのパス設定やautodocの拡張が有効か確認してください。また、モジュールの場所を正しく指定し、automoduleディレクティブを使用しているか確認します。

テーマを変えたい場合

pip install sphinx_rtd_themeなどでテーマをインストールし、conf.pyでhtml_theme = 'sphinx_rtd_theme'のように設定することで見た目を変更できます。

公式のテーマ一覧：https://www.sphinx-doc.org/en/master/usage/theming.html#builtin-themes

非公式のテーマギャラリー：https://sphinx-themes.org/

まとめ

  1. pip install sphinxでインストール
  2. sphinx-quickstartで初期設定ファイルを生成
  3. conf.pyでautodocなどの拡張機能を有効化
  4. make htmlでHTMLドキュメント生成
  5. 生成された_build/html/index.htmlをブラウザで閲覧

以上がSphinxを初めて使う人向けの基本的な流れです。最初は最小限の設定で動かし、徐々にテーマ変更や拡張導入などステップアップしていくとよいでしょう。

-Python