Sphinxドキュメントのビルド性能を改善する#
Sphinxを使った多言語ドキュメントの構築において、ビルド時間が長くなってきたことをきっかけに、性能改善を行いました。この記事では、改善前後の状況や、試行錯誤のプロセス、そして得られた成果を整理しておきます。
背景#
以下のような構成でSphinxを使っていました：
多言語構成：
ja,ensetup.pyにdocコマンドを定義し、python setup.py docでビルドpoetry + poe を使って
poetry run poe docで実行最初のビルド時間： 約1分
初期計測（改善前）#
以下のように計測を行いました。
time poetry run poe doc
出力：
poetry run poe doc 57.11s user 2.96s system 97% cpu 1:01.38 total
この段階では、すべての言語を直列に、かつ -E -a オプション付きでフルビルドしていました。
改善施策の試行#
次のような改善を順に試しました：
-E -aの削除（差分ビルドを有効化）言語ごとの並列ビルド（
multiprocessingによる）静的ファイルコピーの差分対応（filecmpによる判定付き）
Sphinxの内部並列化（
-j autoオプション）コア数や仮想CPU環境による並列効果の検証
注釈
Linuxでは、CPUのスペックは lscpu コマンドで確認できます。
最終構成（ベストプラクティス）#
以下のような構成に落ち着きました：
-E -aを外し、差分ビルドを有効に並列ビルドはあえて使わず、2コア環境では直列が安定
-j autoを用いてSphinx内部の並列処理を有効に静的ファイルのコピーは差分判定付き
改善後の計測結果#
✨ 全ビルド完了。所要時間: 6.23 秒
poetry run poe doc 8.89s user 1.28s system 99% cpu 10.199 total
改善前と比較して ビルド時間が6分の1以下に短縮 されました。
考察と今後#
Sphinxはファイルキャッシュ（doctrees）を活用することで、大きく高速化可能
CPUコア数が少ない環境では並列化の効果は限定的
-j autoによる内部並列化は効果あり言語数が増えたり、仮想環境の構成が変わる場合は、再度並列処理の導入を検討
記事情報
- 著者:
mtakagishi
- 投稿日:
2025-05-27