はじめに¶
Sphinx は、ドキュメントジェネレーター、つまりプレーンテキストのソースファイルのセットをさまざまな出力形式に変換し、相互参照、索引などを自動的に生成するツールです。つまり、reStructuredTextまたはMarkdownドキュメントを多数含むディレクトリがあれば、Sphinx は一連のHTMLファイル、PDFファイル（LaTeX経由）、manページなどを生成できます。
Sphinx は、特に手書きのドキュメントに焦点を当てていますが、ブログ、ホームページ、さらには書籍の生成にも使用できます。Sphinx のパワーの多くは、デフォルトのプレーンテキストマークアップ形式であるreStructuredTextの豊富さと、拡張性の高い機能によるものです。
このドキュメントの目的は、Sphinx が何か、そしてどのように使用できるのかを簡単に紹介することです。読み終えたら、インストールガイドを確認し、Sphinxで使用されるデフォルトのマークアップ形式であるreStructuredTextの紹介に進みます。
一般的なドキュメント作成に関する優れた「入門」として、理由と方法については、Eric Holscher が執筆したWrite the docsも参照してください。
ドキュメントソースの設定¶
Sphinx のプレーンテキストドキュメントソースのコレクションのルートディレクトリは、ソースディレクトリと呼ばれます。このディレクトリには、Sphinx の設定ファイルconf.pyも含まれており、Sphinx がソースを読み取り、ドキュメントをビルドする方法のあらゆる側面を設定できます。[1]
Sphinx には、ソースディレクトリを設定し、いくつかの質問に答えることで最も有用な設定値を含むデフォルトの conf.py を作成する sphinx-quickstart というスクリプトが付属しています。これを使用するには、以下を実行します。
$ sphinx-quickstart
ドキュメント構造の定義¶
sphinx-quickstart を実行したと仮定しましょう。これにより、conf.py とルートドキュメント index.rst を持つソースディレクトリが作成されます。ルートドキュメント の主な機能は、ウェルカムページとして機能し、「目次ツリー」（または toctree）のルートを含むことです。これは、Sphinx が reStructuredText に追加する主要なものの 1 つであり、複数のファイルを単一のドキュメント階層に接続する方法です。
reStructuredText ディレクティブ
toctree は reStructuredText のディレクティブであり、非常に多用途なマークアップです。ディレクティブには、引数、オプション、コンテンツを含めることができます。
引数は、ディレクティブ名の後の二重コロンの直後に記述されます。各ディレクティブは、引数を使用できるかどうか、そしていくつ使用できるかを決定します。
オプションは、引数の後に「フィールドリスト」の形式で記述されます。maxdepth は、toctree ディレクティブのこのようなオプションの 1 つです。
コンテンツは、空行の後にオプションまたは引数の後に続きます。各ディレクティブは、コンテンツを許可するかどうか、そしてコンテンツをどのように処理するかを決定します。
ディレクティブに関するよくある落とし穴は、**コンテンツの最初の行をオプションと同じレベルでインデントする必要がある**ことです。
toctree ディレクティブは最初は空で、次のようになります。
.. toctree::
:maxdepth: 2
ディレクティブのコンテンツにリストされているドキュメントを追加します。
.. toctree::
:maxdepth: 2
usage/installation
usage/quickstart
...
これは、このドキュメントのtoctreeがまさにどのように見えるかです。含めるドキュメントは、ドキュメント名として指定されます。つまり、ファイル名拡張子を省略し、ディレクトリセパレーターとしてスラッシュ（/）を使用します。
こちらも参照してください
toctree ディレクティブについて詳しく読むことができます。
toctreeにリストしたファイルを作成し、コンテンツを追加すると、そのセクションタイトルがtoctreeディレクティブが配置されている場所に挿入されます（maxdepthレベルまで）。また、Sphinx はドキュメントの順序と階層を認識するようになります。（それらにはtoctreeディレクティブ自体を含めることができるため、必要に応じて深くネストされた階層を作成できます。）
コンテンツの追加¶
Sphinx ソースファイルでは、標準のreStructuredTextのほとんどの機能を使用できます。Sphinx によって追加された機能もあります。たとえば、refロールを使用して、移植可能な方法で（すべての出力タイプで動作する）ファイル間の参照を追加できます。
例として、HTML バージョンを表示している場合は、このドキュメントのソースを確認できます。「ソースを表示」リンクをサイドバーで使用してください。
こちらも参照してください
reStructuredTextで、Sphinxによって追加されたマークアップを含む、reStructuredTextの詳細な紹介をご覧ください。
ビルドの実行¶
いくつかのファイルとコンテンツを追加したので、ドキュメントの最初のビルドを作成しましょう。ビルドはsphinx-buildプログラムで開始されます。
$ sphinx-build -M html sourcedir outputdir
ここで、sourcedir はソースディレクトリ、outputdir はビルドされたドキュメントを配置するディレクトリです。-Mオプションはビルダーを選択します。この例では、Sphinx はHTMLファイルをビルドします。
こちらも参照してください
sphinx-build がサポートするすべてのオプションについては、sphinx-build man ページを参照してください。
ただし、sphinx-quickstart スクリプトは Makefile と make.bat を作成し、作業をさらに容易にします。これらは、ビルダーの名前を付けて make を実行することで実行できます。たとえば。
$ make html
これにより、選択したビルドディレクトリにHTMLドキュメントが作成されます。引数なしでmakeを実行すると、使用可能なターゲットを確認できます。
PDFドキュメントを生成するにはどうすればよいですか？
make latexpdf は LaTeX ビルダー を実行し、pdfTeX ツールチェーンをすぐに呼び出します。
オブジェクトの文書化¶
Sphinx の主要な目的の 1 つは、任意のドメインにおけるオブジェクト（非常に一般的な意味での）の簡単な文書化です。ドメインとは、一緒に属するオブジェクトタイプの集合であり、これらのオブジェクトの説明を作成および参照するためのマークアップが付属しています。
最も顕著なドメインは、Python ドメインです。たとえば、Python の組み込み関数 enumerate() を文書化するには、ソースファイルの 1 つに次を追加します。
.. py:function:: enumerate(sequence[, start=0])
Return an iterator that yields tuples of an index and an item of the
*sequence*. (And so on.)
これは次のようにレンダリングされます。
- enumerate(sequence[, start=0])¶
シーケンスのインデックスとアイテムのタプルを生成するイテレータを返します。（以下略）
ディレクティブの引数は、記述するオブジェクトのシグネチャであり、コンテンツはそのドキュメントです。複数のシグネチャを指定でき、それぞれが独自の行に記述されます。
Python ドメインはデフォルトのドメインでもあるため、マークアップにドメイン名をプレフィックスする必要はありません。
.. function:: enumerate(sequence[, start=0])
...
デフォルトドメインのデフォルト設定を維持する場合は、同じ動作をします。
Pythonオブジェクトの他の種類を文書化するためのディレクティブがいくつかあります。たとえば、py:classやpy:methodなどがあります。これらのオブジェクトタイプそれぞれに対応する相互参照ロールもあります。このマークアップは、enumerate()のドキュメントへのリンクを作成します。
The :py:func:`enumerate` function can be used for ...
そしてこれがその証拠です：enumerate()へのリンク。
繰り返しますが、Pythonドメインがデフォルトの場合、py:は省略できます。enumerate()の実際のドキュメントを含むファイルはどちらでも構いません。Sphinxはそれを探し出し、そのリンクを作成します。
各ドメインには、シグネチャの記述方法、フォーマットされた出力の見栄えの良くする方法、C/C++ドメインなどにおけるパラメータタイプへのリンクなどの特定の機能の追加方法に関する特別なルールがあります。
こちらも参照してください
利用可能なすべてのドメインとそのディレクティブ/ロールについては、ドメインを参照してください。
基本設定¶
前述のように、conf.pyファイルは、Sphinxがドキュメントを処理する方法を制御します。Pythonソースファイルとして実行されるこのファイルでは、設定値を割り当てます。上級者向け：Sphinxによって実行されるため、sys.pathの拡張や、ドキュメント化しているバージョンの確認のためのモジュールのインポートなど、高度なタスクを実行できます。
おそらく変更したい設定値は、sphinx-quickstartによって既にconf.pyに配置されており、最初はコメントアウトされています（標準的なPython構文：#は行の残りをコメントアウトします）。デフォルト値を変更するには、ハッシュ記号を削除して値を変更します。sphinx-quickstartによって自動的に追加されない設定値をカスタマイズするには、追加の代入を追加するだけです。
このファイルは、文字列、数値、リストなどにPython構文を使用していることに注意してください。ファイルはデフォルトでUTF-8で保存されます（最初の行のエンコーディング宣言で示されています）。
こちらも参照してください
利用可能なすべての設定値のドキュメントについては、設定を参照してください。
Autodoc¶
Pythonコードを文書化する場合、ソースファイル内のドキュメント文字列に多くのドキュメントを配置することが一般的です。Sphinxは、_autodoc_と呼ばれる拡張機能（拡張機能とは、Sphinxプロジェクトに追加機能を提供するPythonモジュールのことです）を使用して、モジュールからのdocstringを含めることをサポートしています。
こちらも参照してください
autodocの機能の完全な説明については、sphinx.ext.autodocを参照してください。
Intersphinx¶
Pythonドキュメントを含む多くのSphinxドキュメントはインターネット上に公開されています。ドキュメントからそのようなドキュメントへのリンクを作成したい場合は、sphinx.ext.intersphinxを使用できます。
Intersphinxを使用するには、conf.pyでextensionsリストに文字列'sphinx.ext.intersphinx'を追加し、intersphinx_mapping設定値を設定する必要があります。
たとえば、Pythonライブラリマニュアルのio.open()へのリンクを作成するには、intersphinx_mappingを次のように設定する必要があります。
intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
これで、:py:func:`io.open`のような相互参照を作成できます。現在のドキュメントセットに一致するターゲットがない相互参照は、intersphinx_mappingで設定されているドキュメントセットで検索されます（有効なターゲットのリストをダウンロードするには、URLへのアクセスが必要です）。Intersphinxは、:ref:を含む他のいくつかのドメインのロールでも機能しますが、ドメイン以外のロールである:doc:では機能しません。
こちらも参照してください
intersphinxの機能の完全な説明については、sphinx.ext.intersphinxを参照してください。
今後取り上げるトピック¶
脚注