[python] sphinxでドキュメント生成

Last updated at 2025-07-12Posted at 2022-07-28

はじめに

sphinxとはpython製のオートドキュメンテーションツールです。
知的で美しいドキュメントを簡単に作れるらしい。(公式談)
今回初めてsphinxを使って文書を作成してみたので、インストールからビルドまでの流れを簡単にまとめておきます。

環境

OS	Python Ver
Windows10	3.10.5

sphinxパッケージのインストール

仮想環境を立ち上げて、環境内にインストール。

(.venv) pip install sphinx

これで、最低限としてsphinxパッケージのインストールはOK
Read the Docsのテーマが使いたいなら追加でsphinx-rtd-themeを、バージョンごとのドキュメントを作りたい場合はsphinx-multiversionをそれぞれ適宜インストールする。

(.venv) pip install sphinx-rtd-theme sphinx-multiversion

sphinxプロジェクト作成

現在、ディレクトリ構成は以下のようになっています。

for_sphinx_test(root)/
 ┣━.venv/
 ┣━ requirements.txt
 ┗━ pkg/
     ┣━ __pycache__/
     ┣━ test.py
     ┣━ __init__.py
     ┗━ __main__.py

root下にdocsという名前でsphinx用プロジェクトを作成している人が多い様なので、自分もそれに倣って下記コマンドを打ちdocs内にsphinxプロジェクトを作成しました。

(root) sphinx-quickstart docs

docs内にSphinx関係のファイルを作れば削除する際などに比較的楽な気がします

sphinx-quickstartしたときに、色々質問されると思います。

Sphinx 出力用のビルドディレクトリを配置する方法は2つあります。
ルートパス内にある "_build" ディレクトリを使うか、
ルートパス内に "source" と "build" ディレクトリを分ける方法です。
> ソースディレクトリとビルドディレクトリを分ける（y / n） [n]: y

soureceとbuildがごちゃごちゃするのがちょっと嫌なので自分はYを選択して、分けるようにしてます。

他の質問としてプロジェクト名やauthorなど聞かれると思うがミスしたとしても、後でconf.pyで設定し直せるので気楽に答えていけばよいと思います。

sphinxプロジェクトを立ち上げた後のディレクトリ構成は以下のようになる。

for_sphinx_test(root)/
 ┣━ .venv/
 ┣━ requirements.txt
 ┣━ pkg/
 ┃   ┣━ __pycache__/
 ┃   ┣━ test.py
 ┃   ┣━ __init__.py
 ┃   ┗━ __main__.py  
 ┗━ docs/
      ┣━ build/
      ┣━ source/
      ┃     ┣━ _static/
      ┃     ┣━ _templates/
      ┃     ┣━ conf.py
      ┃     ┗━ index.rst
      ┣━ make.bat
      ┗━ makefile

quick-start後に生成されるファイルやディレクトリの用途としては以下の通り。

ディレクトリ名/ファイル名	用途
build	ビルド後に生成されるhtml等のドキュメントソース置き場
_static	cssやJavaScript置き場
_templates	テンプレートを上書きするファイルなどを置く
conf.py	設定ファイル
index.rst	ドキュメントの起点になるファイル
make.bat	(Windows環境)ビルドを行うスクリプトが書かれたバッチファイル
Makefile	(Linux環境)ビルドを行うスクリプトが書かれたファイル

ちなみに、sphinx-quickstartしたときの質問で、buildとsourceを分けなかった場合、sourceディレクトリは生成されず、中のディレクトリとファイルがbuildと同じ階層に置かれることとなります。

conf.pyの設定

初めてビルドする際には、docs配下のconf.pyを少しいじらなければいけない。
いじる内容は主に3つ(うち1個は任意)

(1) パッケージディレクトリへのパス設定
ドキュメント化したいパッケージのパスを設定する必要がある。
今回はpkgのトップ階層がそれにあたる。パスはconf.pyとの相対で取るので下のようにコードを加えればよい

conf.py

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

(2) extensionsの設定
初期状態ではextensionsは空リストになっていると思うがオートドキュメントのために、下の拡張を加える必要がある。
sphinxライブラリに標準で入っているので追加インストールは不要

conf.py

extensions = [
    'sphinx.ext.autodoc',  # ソースコード読み込み用
    'sphinx.ext.viewcode',  # ハイライト済みのソースコードへのリンクを追加
    'sphinx.ext.todo',  # ToDoアイテムのサポート
    'sphinx.ext.napoleon' #googleスタイルやNumpyスタイルでdocstringを記述した際に必要
]

(3) htmlテーマの変更(任意)
初期ではalabasterが設定されているはずです。
自分はsphinx_rtd_themeの方がイケていると思ったのでこちらに変更してみました。

conf.py

html_theme = 'sphinx_rtd_theme'

他にも、quick-startで設定を間違えたり、Ver情報を更新したい時などはconf.pyを変更すれば反映される。

rstファイルの作成

パッケージのパスを指定して、htmlファイルのソースとなるrstファイルを作成していく。

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

公式サイトでは、このような指定がある。
OUTPUT_PATHにはsourceのディレクトリを指せばよいので、rootにいた場合は次のようになる

(root) sphinx-apidoc -f -o docs/source pkg

これでモジュール毎のrstとmodules.rstというファイルが生成されたと思います。
(-f:上書き, -o:ディレクトリがなかったら作成する)

index.rstへの登録

index.rstはhtmlのトップページとして使用される。
ここにapidocで出力されたmodulesを参照させることで、htmlドキュメントが追加される仕組みのようですね。

index.rst


===========================================

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

   modules #これを追加

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`