-

Sphinxは、Pythonコードの説明を自動でHTML化するためのツールです。
ただし、コードを置くだけでは動きません。
どこを読むか、何を目次に載せるか、どの設定で取り込むかを整える必要があります。

結論

Sphinxを使うと、Pythonコードに書いたdocstringをもとに、
関数一覧や説明ページをHTMLとして出力できます。

そのために必要なのは、主に次の4つです。

コードがimportできること
関数やクラスにdocstringがあること
Sphinx用の設定ファイルがあること
トップページとAPIページの導線があること

つまり、「Pythonコード」だけでなく、「設定」と「文書の入口」も一緒に作ると、
SphinxでHTMLを生成できるようになります。

Sphinxとは何か

Sphinxは、技術文書を作るためのツールです。
Pythonでは特に、関数やクラスのdocstringを読み取り、
APIドキュメントを自動生成する用途でよく使われます。

ここで大事なのは、Sphinxは
コードを見て説明文を勝手に想像する道具ではない
という点です。
Sphinxが読むのは、コードそのものと、そこに書かれたdocstringです。

そしてSphinxは、次のような流れでHTMLを作ります。

設定ファイル conf.py を読む
トップページ index.rst から文書構造をたどる
automodule などを通じてPythonモジュールをimportする
docstringを取り込み、HTMLに変換する

だから、Sphinxを使えるようにするには、
コード・設定・目次の3つをそろえる必要があります。

SphinxでHTMLを作るまでの流れ

1. まず、Sphinxの土台を自動生成する

Sphinxでは、最初の文書プロジェクトを一から手で作る必要はありません。
通常は sphinx-quickstart のようなコマンドを使って、
docs/、conf.py、index.rst、Makefile類といった
基本構成を自動生成します。

つまり、Sphinx対応の出発点は
「必要なファイルを自分で全部書くこと」ではなく、
「コマンドで土台を作り、その上に必要な設定やページを足すこと」
です。

2. Pythonコードを、読み取りやすい形にする

土台ができたら、次に見るべきはPythonコード側です。
分析コードが一本の実行スクリプトになっている場合は、
データ読込、前処理、学習、評価、可視化などを関数に分けておくと、
Sphinxで説明しやすくなります。

特に大切なのは、
importしただけで重い処理が走らないことです。
Sphinxはコードを読み込んで情報を取り出すため、
「実行のためのコード」と「説明対象の定義」を分けておくと扱いやすくなります。

3. docstringを書く

Sphinxが自動で取り込む説明の中心はdocstringです。
そのため、主要な関数やクラスに、
「何をするか」「引数は何か」「何を返すか」を書いておきます。

ここで重要なのは、コメントを増やすことではなく、
外から見て必要な説明を、関数やクラスに結び付けておくことです。

4. 自動生成された設定と文書を、プロジェクトに合わせて調整する

自動生成された conf.py や index.rst は、そのままでは最小構成です。
実際に分析コードを説明するには、
対象モジュールを読み込めるように設定したり、
APIページや概要ページを目次につないだりする必要があります。

つまりSphinx対応では、
自動生成された土台に対して、
自分のPythonプロジェクト用の配線を追加する
ことになります。

5. APIページを作って、コードの情報を流し込む

docstringは、書いてあるだけではHTMLページになりません。
そこで、API用のページを作り、
そこに automodule などを置いて、
対象モジュールの情報を流し込みます。

この段階でようやく、
Pythonコードに書かれた説明が文書側へ接続されます。

6. 最後にHTMLをビルドする

ここまで整ったら、最後にビルドコマンドでHTMLを出力します。
具体的なコマンドや確認ポイントは別の記事で扱うとして、
この段階でSphinxは
設定、目次、APIページ、docstringをまとめてHTMLへ変換します。

添付zipでは、何のために何を作ったか

今回の例では、もとのzipに分析コードがあり、
そこへSphinx用の構造を追加しました。

もとの構成

water_potability/
├─ main.py
├─ water_potability.py
├─ data/
│  └─ water_potability.csv
└─ output/
   ├─ figures/
   └─ tables/

この状態でも分析はできます。
ただし、Sphinxが読むための設定や入口ページはありません。

Sphinx対応後の構成

water_potability/
├─ __init__.py
├─ main.py
├─ water_potability.py
├─ pyproject.toml
├─ README_SPHINX.md
├─ data/
├─ output/
└─ docs/
   ├─ requirements.txt
   ├─ Makefile
   ├─ make.bat
   └─ source/
      ├─ conf.py
      ├─ index.rst
      ├─ overview.rst
      ├─ quickstart.rst
      └─ api/
         ├─ index.rst
         ├─ package.rst
         ├─ main.rst
         └─ module.rst

各ファイルの役割

ここで追加したファイルには、それぞれ役割があります。

__init__.py：パッケージとして扱いやすくする
pyproject.toml：依存関係を定義する
README_SPHINX.md：Sphinx対応版の使い方をまとめる
docs/source/conf.py：Sphinxの設定を行う
docs/source/index.rst：文書の入口を作る
overview.rst：プロジェクト概要を説明する
quickstart.rst：ビルド手順を説明する
api/*.rst：docstringの置き場所を作る
docs/requirements.txt：Sphinx用依存関係を分けて管理する

情報の流れ

この構成になると、情報は次のように流れます。

water_potability.py / main.py
        ↓
docstring
        ↓
api/main.rst / api/module.rst の automodule
        ↓
index.rst の toctree
        ↓
conf.py の設定
        ↓
make html
        ↓
_build/html/ にHTML出力

つまり、
コードの情報が、docstring → APIページ → 目次 → HTML
という順で流れていくわけです。

この例で分かること

添付zipはあくまで一例ですが、考え方は一般化できます。

分析用のPythonコードをSphinx対応にするときは、
次のように考えると整理しやすいです。

まず、どのPythonファイルを説明対象にするか決める
そのファイルにdocstringを書く
Sphinx用の docs/ を作る
conf.py で読み方を設定する
index.rst とAPIページで導線を作る
make html でHTMLを出力する

まとめ

Sphinxとは、
Pythonコードとdocstringを材料にして、
目次つきのHTMLドキュメントを作るツールです。

そのためには、
コードを書くことに加えて、
設定ファイル・入口ページ・APIページを作る
必要があります。

添付zipの例で見ると、
もとの分析コードに対して
docs/、
conf.py、
index.rst、
api/*.rst、
__init__.py、
pyproject.toml
を足すことで、
Sphinxが「読めるプロジェクト」になります。

ここまで分かれば、
Sphinxを知らない状態からでも、
どのファイルを何のために作ればHTMLが出せるのか
を追えるようになります。

ロビー
書架：工学と解析
館内案内

結論