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

1Sphinx とは

Sphinx は Python コードの中の docstring（説明文字列） を読み取って、HTML のドキュメントサイトを自動で組み立てるツールだ。

water_potability/analysis.py には load_data()・evaluate_model() など11個の関数が書かれており、それぞれ :param: や :return: 付きの docstring がある。Sphinx はこれを読んで、引数テーブル・戻り値・例外一覧を含むHTMLページを自動生成する。自分でHTMLを一行も書く必要はない。

2water_potability プロジェクトの構成

添付のファイル構造を整理すると、Sphinx に関係する部分は次のとおりだ。

この章はコピペで進める。理屈は4章以降に書いたので、まずここだけ読めばドキュメントが出来上がる。

3-1. インストール

プロジェクトルート（water_potability_html/）で実行する。

3-2. quickstart ― docs フォルダを生成する

この手順は すでに docs/ フォルダがある場合はスキップ する。今回の water_potability プロジェクトには既に docs/ が存在しているので読み飛ばしてよい。新しくゼロから始める場合の参考として示す。

> Separate source and build directories? (y/n) y
> Project name: Water Potability Analysis
> Author name(s): Matsun
> Project release []: 0.1.0
> Project language [en]: ja

3-3. conf.py ― 実際のファイルをそのまま使う

今回のプロジェクトには docs/source/conf.py が既に用意されている。内容を確認しておこう。

import os, sys
from pathlib import Path

# ① パス設定 ─ Sphinx がコードをインポートできるようにする
ROOT = Path(__file__).resolve().parents[2]  # docs/source/ から2段上 = プロジェクトルート
sys.path.insert(0, str(ROOT))

# ② プロジェクト情報
project   = 'Water Potability Analysis'
copyright = '2026, Matsun'
author    = 'Matsun'
release   = '0.1.0'

# ③ 拡張機能 ─ 最重要
extensions = [
    'sphinx.ext.autodoc',    # docstring から自動でドキュメント生成
    'sphinx.ext.napoleon',   # Google/NumPy スタイルの docstring を解釈
    'sphinx.ext.viewcode',   # ソースコードへのリンクを追加
    'sphinx.ext.todo',       # TODO ディレクティブ
]

# ④ autodoc の設定
autodoc_default_options = {
    'members':        True,
    'member-order':   'bysource',  # ソース定義順に並べる
    'undoc-members':  False,       # docstring なしは除外
    'show-inheritance': True,
}

# ⑤ napoleon の設定
napoleon_google_docstring        = True
napoleon_numpy_docstring         = True
napoleon_use_admonition_for_notes = True

language   = 'ja'
html_theme = 'sphinx_rtd_theme'

3-4. sphinx-apidoc ― .rst スタブを自動生成する

今回も既に docs/source/ に analysis.rst・main.rst・modules.rst が存在する。docstring を修正した後や新しい関数を追加した際に 再実行して .rst を更新 する。

プロジェクトルートから実行する。最後の引数は ドキュメント化したいパッケージのパスだ。

実行後、docs/source/ の .rst が更新される。実際の中身は次のとおりだ。

water_potability
================

.. toctree::
   :maxdepth: 4

   main
   analysis

analysis module
===============

.. automodule:: water_potability.analysis
   :members:
   :undoc-members:
   :show-inheritance:

# docs/source/index.rst の toctree（実際のファイル）
.. toctree::
   :maxdepth: 2
   :caption: Contents:

   modules  ← modules.rst を含める（modules.rst がさらに main/analysis を束ねる）

3-5. make html ― ビルドして確認する

docs/ フォルダに移動して make html を実行する。

cd docs
make html

# 成功すると:
# build succeeded.
# The HTML pages are in build/html.

ビルド後、docs/build/html/index.html をブラウザで開く。

# macOS
open docs/build/html/index.html

# Windows
start docs/build/html/index.html

情報は次の流れで一方通行に処理される。

Path 設定 ― なぜ parents[2] なのか

今回の conf.py では os.path.abspath ではなく pathlib.Path を使っている。

ROOT = Path(__file__).resolve().parents[2]
sys.path.insert(0, str(ROOT))

# Path(__file__) = docs/source/conf.py の絶対パス
# .parents[0] = docs/source/
# .parents[1] = docs/
# .parents[2] = water_potability_html/  ← プロジェクトルート
#
# sys.path に追加することで Python は
# water_potability/ パッケージを発見できるようになる

autodoc は .. automodule:: water_potability.analysis という命令を受けると、Python が実際に water_potability.analysis をインポートしてその docstring を取得する。パスが通っていないと ImportError になる。

extensions の各役割

今回のプロジェクトでは目次が 2段構成になっている。

核心は .. automodule:: 命令だ。

analysis module
===============

.. この1行が核心。autodoc に「water_potability.analysis を
   Python としてインポートして、全メンバーの docstring を
   HTML に変換しろ」と指示する
.. automodule:: water_potability.analysis
   :members:
   :undoc-members:
   :show-inheritance:

analysis.py は RST スタイル（:param:・:type:・:return:・:rtype:・:raises:） を採用している。napoleon 拡張がなくても Sphinx 本来の書き方として認識される。

analysis.py の全関数一覧

11個の関数がすべて docstring を持ち、ドキュメントに反映される。

docstring の実例 ― load_data()

実際の load_data() の docstring と、それが HTML でどう表示されるかを対応させて確認する。

def load_data(csv_path: Path) -> pd.DataFrame:
    """ローカル CSV を読み込んで DataFrame を返す。

    :param csv_path: 読み込む CSV ファイルのパス。
    :type csv_path: Path
    :return: 読み込んだデータ。
    :rtype: pd.DataFrame
    :raises FileNotFoundError: 指定されたファイルが存在しない場合。
    :raises ValueError: CSV の読み込みに失敗した場合。
    """

定数もドキュメント化される

analysis.py の先頭には定数が定義されているが、docstring がないためデフォルト設定（undoc-members: False）では非表示になる。表示させたい場合は #: でコメントを付ける。

# 現在のコード（undoc-members: False なので非表示）
TARGET_COL   = "Potability"
RANDOM_STATE = 42
TEST_SIZE    = 0.2

# #: を付けると Sphinx が認識して表示される
TARGET_COL   = "Potability"  #: 目的変数のカラム名
RANDOM_STATE = 42             #: 乱数シード（再現性確保のため固定）
TEST_SIZE    = 0.2            #: テストデータの割合（全体の 20%）

まず確認するチェックリスト

• conf.py の ROOT = Path(__file__).resolve().parents[2] が water_potability_html/ を指しているか（parents[2] の数が正しいか）
• docs/source/index.rst の toctree に modules が書いてあるか
• docs/source/modules.rst の toctree に main と analysis が書いてあるか
• toctree のインデントが 半角スペース3個 になっているか（Tab・2個・4個はNG）
• water_potability/__init__.py が存在するか（パッケージとして認識される必要がある）
• 新しい関数を追加したあと sphinx-apidoc を再実行して .rst を更新したか

エラーメッセージ別対処

⚠ ImportError: No module named ‘pandas’（または matplotlib / sklearn）
▸



⚠ WARNING: document isn’t included in any toctree
▸



⚠ analysis.html は生成されるが、関数の説明が空
▸



⚠ _save_table() がドキュメントに表示されてほしくない
▸



⚠ 日本語のドキュメントが文字化けする
▸

9まとめ

以降は analysis.py の docstring を書き直したら make html を再実行するだけだ。コードとドキュメントが常に同期した状態で維持できる。