コードからの自動ドキュメント生成¶

チュートリアルの前のセクションでは、Sphinx で Python 関数を手動でドキュメント化しました。ただし、関数のシグネチャが同じではなかったため、説明はコード自体と同期していませんでした。さらに、情報を 2 か所に記述するのではなく、Python docstringをドキュメントで再利用できると便利です。

幸いなことに、autodoc 拡張機能はこの機能を提供します。

autodoc を使用したシグネチャと docstring の再利用¶

autodoc を使用するには、まず有効な拡張機能のリストに autodoc を追加します。

docs/source/conf.py¶

extensions = [
    'sphinx.ext.duration',
    'sphinx.ext.doctest',
    'sphinx.ext.autodoc',
]

次に、.. py:function ディレクティブの内容を、元の Python ファイルの関数 docstring に次のように移動します。

lumache.py¶

def get_random_ingredients(kind=None):
    """
    Return a list of random ingredients as strings.

    :param kind: Optional "kind" of ingredients.
    :type kind: list[str] or None
    :raise lumache.InvalidKindError: If the kind is invalid.
    :return: The ingredients list.
    :rtype: list[str]

    """
    return ["shells", "gorgonzola", "parsley"]

最後に、Sphinx ドキュメントの .. py:function ディレクティブを autofunction に置き換えます。

docs/source/usage.rst¶

you can use the ``lumache.get_random_ingredients()`` function:

.. autofunction:: lumache.get_random_ingredients

これで HTML ドキュメントをビルドすると、出力は同じになります。コード自体から生成されるという利点があります。Sphinx は docstring から reStructuredText を取得して含め、適切な相互参照も生成しました。

他のオブジェクトからドキュメントを自動生成することもできます。たとえば、InvalidKindError 例外のコードを追加します。

lumache.py¶

class InvalidKindError(Exception):
    """Raised if the kind is invalid."""
    pass

.. py:exception ディレクティブを autoexception に次のように置き換えます。

docs/source/usage.rst¶

or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients`
will raise an exception.

.. autoexception:: lumache.InvalidKindError

ここでも、make html を実行した後、出力は以前と同じになります。

包括的な API リファレンスの生成¶

sphinx.ext.autodoc を使用すると、コードとドキュメントの同期をはるかに簡単に行うことができますが、ドキュメント化するすべてのオブジェクトに対して auto* ディレクティブを記述する必要があります。Sphinx はさらに別のレベルの自動化を提供します。autosummary 拡張機能です。

autosummary ディレクティブは、必要なすべての autodoc ディレクティブを含むドキュメントを生成します。これを使用するには、まず autosummary 拡張機能を有効にします。

docs/source/conf.py¶

extensions = [
   'sphinx.ext.duration',
   'sphinx.ext.doctest',
   'sphinx.ext.autodoc',
   'sphinx.ext.autosummary',
]

次に、次の内容で新しい api.rst ファイルを作成します。

docs/source/api.rst¶

API
===

.. autosummary::
   :toctree: generated

   lumache

新しいドキュメントをルート toctree に含めることを忘れないでください。

docs/source/index.rst¶

Contents
--------

.. toctree::

   usage
   api

最後に、make html を実行して HTML ドキュメントをビルドすると、2 つの新しいページが含まれます。

api.html。 docs/source/api.rst に対応し、autosummary ディレクティブに含めたオブジェクト (この場合は 1 つだけ) のテーブルが含まれています。
generated/lumache.html。新しく作成された reStructuredText ファイル generated/lumache.rst に対応し、モジュールのメンバーのサマリー (この場合は 1 つの関数と 1 つの例外) が含まれています。

Summary page created by autosummary — autosummary によって作成されたサマリーページ¶

サマリーページの各リンクをクリックすると、対応する autodoc ディレクティブを最初に使用した場所 (この場合は usage.rst ドキュメント) に移動します。

注記

生成されたファイルは、Jinja2 テンプレートに基づいており、カスタマイズできますが、このチュートリアルの範囲外です。