より高度な Sphinx のカスタマイズ¶
コア Sphinx で可能なカスタマイズの範囲を超えてドキュメンテーションをカスタマイズする 2 つの主な方法があります。それは拡張機能とテーマです。
ビルトイン拡張機能の有効化¶
これらの設定値に加え、拡張機能を使用することで Sphinx をさらにカスタマイズすることができます。Sphinx には数多くのビルトインの拡張機能が付属しており、コミュニティで多くのものがメンテナンスされています。
例えば、sphinx.ext.duration拡張機能を有効にするには、extensionsリストをconf.pyで探し出し、次のように 1 つ要素を追加します。
docs/source/conf.py¶
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.duration',
]
これ以降は、ドキュメンテーションを生成するたびにコンソール出力の最後に次のような短い期間報告が表示されるようになります。
(.venv) $ make html
...
The HTML pages are in build/html.
====================== slowest reading durations =======================
0.042 temp/source/index
サードパーティー HTML テーマの使用¶
一方、テーマはドキュメンテーションの見た目をカスタマイズする方法です。Sphinx には数多くのビルトインテーマがありますが、サードパーティー製のテーマもあります。
例えば、HTML ドキュメンテーションでFuroサードパーティーテーマを使用するには、まず Python 仮想環境でpipを使用してインストールする必要があります。次のように行います。
(.venv) $ pip install furo
そして、html_theme変数をconf.pyで見つけ出し、次のように値を置き換えます。
docs/source/conf.py¶
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'furo'
このように変更すると、HTML ドキュメンテーションが新しい外観になっていることがわかります。
Furo テーマを使用した Lumache の html ドキュメンテーション¶