拡張機能¶
多くのプロジェクトではドキュメントに特別な機能が必要となるため、Sphinx ではビルドプロセスに「拡張機能」を追加できます。各拡張機能は、ドキュメント処理のほぼすべての側面を変更できます。
この章では、Sphinx にバンドルされている拡張機能について説明します。独自の拡張機能の作成に関する API ドキュメントについては、Sphinx API を参照してください。
組み込み拡張機能¶
これらの拡張機能は組み込まれており、extensions 構成値のそれぞれのエントリでアクティブ化できます。
sphinx.ext.autodoc– docstring からドキュメントを含めるsphinx.ext.autosectionlabel– タイトルを使用してセクションを参照できるようにするsphinx.ext.autosummary– autodoc の概要を生成するsphinx.ext.coverage– ドキュメントカバレッジの統計を収集するsphinx.ext.doctest– ドキュメント内のスニペットをテストするsphinx.ext.duration– Sphinx の処理時間を測定するsphinx.ext.extlinks– 外部リンクを短縮するためのマークアップsphinx.ext.githubpages– GitHub Pages に HTML ドキュメントを公開するsphinx.ext.graphviz– Graphviz グラフを追加するsphinx.ext.ifconfig– 構成に基づいてコンテンツを含めるsphinx.ext.imgconverter– Imagemagick を使用した参照画像コンバーターsphinx.ext.inheritance_diagram– 継承図を含めるsphinx.ext.intersphinx– 他のプロジェクトのドキュメントへのリンクsphinx.ext.linkcode– ソースコードへの外部リンクを追加する- Sphinx での HTML 出力用の数式サポート
sphinx.ext.napoleon– NumPy および Google スタイルの docstring のサポートsphinx.ext.todo– TODO 項目のサポートsphinx.ext.viewcode– 強調表示されたソースコードへのリンクを追加する
サードパーティ製拡張機能¶
sphinx-contrib organization で、ユーザーによって提供されたいくつかの拡張機能を見つけることができます。この organization に拡張機能を含める場合は、github-administration プロジェクトで提供されている手順に従ってください。これはオプションであり、他の場所でホストされている拡張機能もいくつかあります。awesome-sphinxdoc および sphinx-extensions プロジェクトは両方とも、厳選された Sphinx パッケージのリストです。多くのパッケージは、Sphinx 拡張機能とテーマに対して、それぞれ Framework :: Sphinx :: Extension および Framework :: Sphinx :: Theme trove 分類子を使用しています。
独自の拡張機能の配置場所¶
プロジェクトにローカルな拡張機能は、プロジェクトのディレクトリ構造内に配置する必要があります。Python のモジュール検索パスである sys.path を、Sphinx がそれらを見つけられるように適切に設定します。たとえば、拡張機能 foo.py がプロジェクトルートの exts サブディレクトリにある場合は、conf.py に次のように記述します。
import sys, os
sys.path.append(os.path.abspath('exts'))
extensions = ['foo']
拡張機能を sys.path 上の他の場所 (例: site-packages ディレクトリ) にインストールすることもできます。