Sphinxによるマニュアル・APIリファレンスページ作成マニュアル

作成例: プロジェクト全体ドキュメント — 第30回結晶工学セミナー(2025) 神谷担当ドキュメント
- ソースを含むファイル: jsap-seminar2025.zip

上記作成例プロジェクトのディレクトリ構成

jsap-seminar2025/
├── build/             # 生成されたHTMLがここに入る
├── source/            # 編集するファイル（.rst / .md / conf.py）
│   ├── page010mu_fit/ # 各プロジェクトのフォルダ
│   │   ├── index.rst  # サブページのindex.html
│   │   ├── api.rst    # APIリファレンスページ
│   │   ├── mu_fit.py  # プログラムソース
│   │   ├── mu_fit_usage.md  # マニュアルMarkdown。プログラムソースなど、他のファイル名と同じにできない
│   │   └── index.rst  # サブページのindex.html
│   ├── conf.py        # 全体の設定
│   └── index.rst      # 全体の目次
└── make.bat           # Windows用ビルド実行ファイル

Sphinxの注意

automodule で docstring などを読み込むプログラム hogehoge.py は、
- ライブラリとして読み込める必要がある
- ファイル名に - は使えない
- ファイル名、パッケージ名は数字では始められない
- サブディレクトリに連番を入れて自動ソートさせる場合は、page010 などから始める
- 引数無しで実行しても正常終了する必要がある
以下のコマンドで確認する。
```
python -m hogehoge
python -c "import hogehoge"
```
サブディレクトリ subdir にあるプログラムを automodule で読み込む場合は、package にしたほうがいい
- 空の __init__.py を hogehoge.py ディレクトリ (source\subdir) に置く
- conf.py で、conf.py ディレクトリをライブラリパスに入れる
  
  current_dir = os.path.abspath(os.path.dirname(file)) sys.path.insert(0, current_dir)
hogehoge.py が同じディレクトリのライブラリを呼ぶ場合、conf.py でライブラリパスを指定する必要がある
```
sys.path.insert(0, os.path.join(current_dir, 'sbdir'))
```

インストール

pip install sphinx sphinx-rtd-theme myst-parser pydata-sphinx-theme

プロジェクト作成

ディレクトリ作成

mkdir jsap-seminar2025
chdir jsap-seminar2025

初期ファイル作成
```
sphinx-quickstart
```

HTMLをビルド

必要があれば
```
make clean
```
実行
```
make.bat html
```

公開

build\html 内のファイルを Web サーバにコピー

Windows の場合は robocopy
Linux の場合は rsync などを使うと便利

robocopy .\build\html\ \サーバーパス\docs /MIR /Z /W:5 /R:3

リリースバッチファイルの例:

@echo off
setlocal

:: 1. SphinxでHTMLをビルド
call make.bat html

:: 2. サーバーの共有フォルダへ同期
:: 送信元: .\build\html
:: 送信先: \\ServerName\SharePath\xrd_docs
set SRC=.\build\html
set DST=\\ServerName\SharePath\xrd_docs

echo 同期を開始します...
robocopy "%SRC%" "%DST%" /MIR /Z /W:5 /R:3 /FFT /XJD /NP

echo 同期が完了しました。
pause

html/index.html にアクセス

設定

source\copy.py で基本的な設定を行う
HTML のソースは reStructuredText (.rst) か Markdown (.md) で作る
source\index.rst / .md に、他の .rst / .md へのリンクを張る
API リファレンスでは、Python ソースファイルのモジュールを読み込み、docstring を使って自動出力する
- Python ソースファイルを import できるように、conf.py で sys.path を設定する
- Python ソースファイルが階層構造になっている場合、__init__.py（空ファイルで OK）を置いて package にしておくと、パッケージツリーとして import できる

`source/conf.py` の例

import os
import sys

# conf.py から見た相対パスで、ソースコードのルートを指定する
current_dir = os.path.abspath(os.path.dirname(__file__))
sys.path.insert(0, os.path.abspath('..'))
sys.path.insert(0, current_dir)
sys.path.insert(0, os.path.join(current_dir, 'page070schrodinger1d'))

project = '第30回結晶工学セミナー(2025) 神谷担当'
copyright = '2026, T.Kamiya'
author = 'T.Kamiya'
release = ''

templates_path = ['_templates']
html_static_path = ['_static']
exclude_patterns = ["build", "_build", "Thumbs.db", ".DS_Store", "__pycache__"]

autosummary_generate = True
language = 'ja'

# API リファレンスのオブジェクト名の前にモジュール名を表示しない
add_module_names = False

# 拡張機能の追加
extensions = [
    'sphinx.ext.autodoc',      # ソースコードからドキュメント生成
    'sphinx.ext.napoleon',     # Google/NumPyスタイルをサポート
    'sphinx.ext.viewcode',     # ソースコードへのリンクを表示
    'sphinx.ext.mathjax',      # docstring の LaTeX をレンダリング
    'myst_parser',             # Markdown (.md) をサポート
    'sphinx_rtd_theme',        # Read the Docs テーマ
]

# pandocの数式書式 $$LaTeX$$に対応させる
myst_enable_extensions = [
    "dollarmath",
    "amsmath",
]

# Markdown ファイルの拡張子を認識させる
source_suffix = {
    '.rst': 'restructuredtext',
    '.md': 'markdown',
}

# テーマ設定
html_theme = 'sphinx_rtd_theme'

# サイドバーやナビゲーションの設定
html_theme_options = {
    'navigation_depth': 4,
    'collapse_navigation': False,
}

# 全ページでサイドバーを表示
html_sidebars = {
    "**": ["sidebar-nav-bs"]
}

# GitHub 連携設定
html_context = {
    'display_github': True,
    'github_user': "yourname",
    'github_repo': "yourrepo",
    'github_version': "main",
    'conf_py_path': "/docs/",
    'doc_path': "docs",
}

`source/index.rst` の例

注意:

インデントは 3 つ以上（ディレクティブ .. toctree:: などの文字の始まりに合わせる）
空行は重要

書式:

1行目: Webページのトップタイトル
1行目と同じ長さの =
空行
toctree: 左サイドバーメニューの設定
- インデント 3 つ: メニューの設定
空行
- インデント 3 つ: メニューのリンク先。ワイルドカードが使える。表示順を制御する場合は、連番を付けるのが簡単

例:

プロジェクト全体ドキュメント
========================

.. toctree::
   :maxdepth: 2
   :caption: メインメニュー:
   :hidden:
   :glob:

   *_page/index

`source/page010mu_fit` の例

ソースコード、マニュアル Markdown、__init__.py を置く
index.rst を置き、source/index.rst からリンクを張る
index.rst には、マニュアル Markdown、API リファレンスページ (api.rst) などへのリンクを張る

`source/page010mu_fit/index.rst` の例

書式:

1行目: Webページのトップタイトル
1行目と同じ長さの =
空行
toctree: 左サイドバーメニューの設定
- インデント 3 つ: メニューの設定
空行
- インデント 3 つ: メニューのリンク先。ワイルドカードが使える。表示順を制御する場合は、連番を付けるのが簡単

例:

mu_fit Project ドキュメント
=====================

.. toctree::
   :maxdepth: 1

   mu_fit_usage
   api

`source/page010mu_fit/mu_fit_usage`

ソースコードから生成AIで docstring を追加する。

プロンプト例:

ソースファイルを添付することを想定。

システム指示:

あなたはPythonのドキュメンテーションエンジニアです。
添付するソースコードの内容を解析し、Sphinx (reStructuredText) 形式に最適化された高品質なDocstringのみを生成してください。

【絶対遵守ルール】

既存のロジック（実行コード）は一切変更しないこと。
出力は、既存のコードにDocstringを挿入した「完成版のコード全体」として出力すること。
各関数・クラスの冒頭に、適切な """Docstring""" を追加すること。

【Docstringの構成要素】

概要: 1行で何をする関数か記述。
詳細説明: 必要に応じて動作の詳細を記述。
引数 (Parameters): :param name: 形式で型と説明を記述。
戻り値 (Returns): :returns: 形式で型と説明を記述。
関連リンク: モジュールの冒頭に、別のドキュメントへのリンク（例: :doc:\usage``）を含めること。

`source/page010mu_fit/api.rst` の例

書式:

1行目: Webページのトップタイトル
1行目と同じ長さの =
空行
必要であれば .. currentmodule:: 010mu_fit_page.mu_fit
空行
.. automodule:: 010mu_fit_page.mu_fit
- :members:

例:

mu_fit プログラム仕様
===================

.. currentmodule:: 010mu_fit_page.mu_fit

.. automodule:: 010mu_fit_page.mu_fit
   :members:

デフォルトでは、API リファレンスのオブジェクト名に automodule: のモジュール名が追加される。
これを抑制する場合は、conf.py で次を設定する。

# オブジェクト名の前にモジュール名を表示しないようにする
add_module_names = False

Sphinxによるマニュアル・APIリファレンスページ作成マニュアル

上記作成例プロジェクトのディレクトリ構成

Sphinxの注意

インストール

プロジェクト作成

HTMLをビルド

公開

設定

source/conf.py の例

source/index.rst の例

source/page010mu_fit の例

source/page010mu_fit/index.rst の例

source/page010mu_fit/mu_fit_usage