Sphinx メモ
目次
セットアップ & ビルド
関連ライブラリをインストール。
sphinx_rtd_theme と sphinx のバージョン互換性に注意。
pip install "sphinx>=8.2,<9" sphinx_rtd_theme sphinx_mdinclude sphinx_autobuild
Graphviz を使う場合はそれも。
# Linux の場合
sudo apt-get install graphviz
# Windows の場合
winget install Graphviz.Graphviz
初期設定
# bash, zsh の場合
sphinx-quickstart docs/sphinx --sep -l en --ext-autodoc --ext-viewcode
# git/uv をベースにした powershell の場合の例
sphinx-quickstart docs/sphinx --sep -l en `
-p $((uv version --output-format json | ConvertFrom-Json).package_name) `
-a $(git config --get user.name) `
-r $((uv version --output-format json | ConvertFrom-Json).version) `
--ext-autodoc --ext-viewcode `
--ext-githubpages `
--extensions sphinx.ext.apidoc `
--extensions sphinx_mdinclude `
--extensions sphinx.ext.graphviz `
--extensions sphinx.ext.inheritance_diagram
初期化後に以下を設定。リンク先には例。：
ビルドは sphinx-build。
上記の conf.py の通り設定しておけば sphinx-apidoc は不要。
# see
sphinx-build ./docs/sphinx/source ./docs/sphinx/build
拡張機能
- sphinx.ext.autodoc：docstring からドキュメント自動生成
- sphinx.ext.napoleon: numpy/Google スタイルの docstring 対応 (reStructured text 形式には不要)
- sphinx.ext.viewcode: ソースコードへの link を追加
- sphinx.ext.graphviz: 各種図生成
- sphinx.ext.inheritance_diagram：継承関係図生成
- sphinx_mdinclude: Markdown ファイルの読込
- インストールコマンド:
pip install sphinx-mdinclude
- インストールコマンド:
reStructuredText
class Hoge:
"""
テストクラス
"""
#: 保存した文字列
member: str
def fuga(self, arg: str) -> int:
"""
テストメソッド
:param arg: カウントする文字
:return: 文字数
"""
self.member = arg
return len(arg)
Tips
- docstring からのドキュメント自動生成には sphinx.ext.autodoc が必要なため注意
- 現在は
conf.pyのsys.path変更は不要。sphinx-apidoc/sphinx-buildの引数でソースのパスを適切に設定。 -
Module 化していない場合に __init__.py を作っていると不具合が生じるため注意
- Markdown から作成
pip install sphinx-mdinclude- conf.py の extension に sphinx_mdinclude を追加
- 対応する rst ファイルを作成
- 必要に応じて index.rst などに 上記3. のリンクを作成
トラブルシューティング
- 出力にあたり以下が必要。対象ファイルの出力がうまくなされない。
- モジュール があるフォルダには __init__.py を配置して認識させる
- 相対パスは
from . import hoge等とする - 使用しているライブラリは sphinx build をする環境にインストール
- パス名に “-“ は厳禁。うまく認識しない。
- LaTeX のビルドは LuaTex の場合は日本語の改行がおかしくなる。XeTeX 推奨。