sphinx.ext.napoleon – NumPy および Google スタイルの docstring をドキュメントに取り込む

モジュールの作者: Rob Ruana

バージョン 1.3 で追加.

Napoleon - Marching toward legible docstrings

以下のようなdocstringを書こうとしてみたことはあるでしょうか。

:param path: The path of the file to wrap
:type path: str
:param field_storage: The :class:`FileStorage` instance to wrap
:type field_storage: FileStorage
:param temporary: Whether or not to delete the file when the File
   instance is destructed
:type temporary: bool
:returns: A buffered writable file descriptor
:rtype: BufferedFileStorage

ReStructuredText は偉大ですが、視覚的に高密度になり、 docstrings が読み難くなります。同じものを`Google Python Style Guide`_で書き直したものと乱雑さを比較してみましょう:

Args:
    path (str): The path of the file to wrap
    field_storage (FileStorage): The :class:`FileStorage` instance to wrap
    temporary (bool): Whether or not to delete the file when the File
       instance is destructed

Returns:
    BufferedFileStorage: A buffered writable file descriptor

はるかに読みやすいですよね。

Napoleonは、 NumPy スタイルおよび Google`_スタイル(`Khan Academy`_が推奨しているスタイル)の両方でSphinxがパースできるようにしてくれる :doc:../extensions` です。

Napoleon はSphinx がパースしようとする前に、`NumPy`_スタイルと`Google`_スタイルの docstring を reStructuredText に変換するプリプロセッサです。 これはSphinx がドキュメントを処理する間の中間ステップで起こるので、実際のソースコードの docstrings を変更することは全くありません。

Getting Started

  1. After setting up Sphinx to build your docs, enable napoleon in the Sphinx conf.py file:

    # conf.py
    
    # Add autodoc and napoleon to the extensions list
    extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']
    
  2. `sphinx-apidoc`を使用して、ご自身のAPIドキュメンテーションをビルドしましょう:

    $ sphinx-apidoc -f -o docs/source projectdir
    

Docstrings

Napoleon interprets every docstring that autodoc can find, including docstrings on: modules, classes, attributes, methods, functions, and variables. Inside each docstring, specially formatted Sections are parsed and converted to reStructuredText.

All standard reStructuredText formatting still works as expected.

Docstring Sections

以下のセクションのヘッダーすべてをサポートしています:

  • Args (alias of Parameters)
  • Arguments (alias of Parameters)
  • Attributes
  • Example
  • Examples
  • Keyword Args (alias of Keyword Arguments)
  • Keyword Arguments
  • メソッド
  • Note
  • Notes
  • Other Parameters
  • Parameters
  • Return (alias of Returns)
  • Returns
  • Raises
  • References
  • See Also
  • 課題
  • Warning
  • Warnings (alias of Warning)
  • Warns
  • Yield (Yieldsの別名)
  • Yields

Google vs NumPy

Napoleon は2つのスタイルの docstring、GoogleNumPy に対応しています。この2つのスタイルの主な違いは、Googleはセクションの区切りにインデントを使い、それに対してNumPyはアンダーラインを使うことです。

Googleスタイル:

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Args:
        arg1 (int): Description of arg1
        arg2 (str): Description of arg2

    Returns:
        bool: Description of return value

    """
    return True

NumPyスタイル:

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

    Returns
    -------
    bool
        Description of return value

    """
    return True

NumPyスタイルはより垂直スペースを要する傾向にあり、それに対してGoogleスタイルはより水平スペースを使用する傾向にあります。Googleスタイルは短くてシンプルなdocstringでは読みやすい傾向にあり、それに対してNumPyスタイルは長く深層的なdocstringで読みやすくなる傾向にあります。

Khan Academy は、Googleスタイルの使用を推奨しています。

スタイルのあいだの選択は大部分が美的感覚のものですが、2つのスタイルは混用するべきではありません。ご自身のプロジェクトでひとつのスタイルを選び、一貫させましょう。

型アノテーション

PEP 484 では、Python のコード内で型を表す標準的な方法を導入しました。これは型を直接、docstrings内で表すことの代替手段です。PEP 484 にそって型を表す一つの利点は、タイプチェッカーとIDEがその情報を静的コード解析で利用できることです。

Google style with Python 3 type annotations:

def func(arg1: int, arg2: str) -> bool:
    """Summary line.

    Extended description of function.

    Args:
        arg1: Description of arg1
        arg2: Description of arg2

    Returns:
        Description of return value

    """
    return True

Google style with types in docstrings:

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Args:
        arg1 (int): Description of arg1
        arg2 (str): Description of arg2

    Returns:
        bool: Description of return value

    """
    return True

注釈

Python 2/3 compatible annotations は現在のところSphinxでサポートされていません。また、ドキュメント上に登場することもあありません。

設定:

以下のリストは、napoleon で使われる設定とそのデフォルト値です。これらの設定はSphinx の`conf.py`で変更できます。”sphinx.ext.autodoc” と “sphinx.ext.napoleon” の両方が conf.py で有効になっていることを確認しましょう:

# conf.py

# Add any Sphinx extension module names here, as strings
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']

# Napoleon settings
napoleon_google_docstring = True
napoleon_numpy_docstring = True
napoleon_include_init_with_doc = False
napoleon_include_private_with_doc = False
napoleon_include_special_with_doc = True
napoleon_use_admonition_for_examples = False
napoleon_use_admonition_for_notes = False
napoleon_use_admonition_for_references = False
napoleon_use_ivar = False
napoleon_use_param = True
napoleon_use_rtype = True
napoleon_google_docstring

True にすると Google style のdocstringsをパースします。False にするとGoogleスタイルのdocstring対応は無効化されます。 デフォルトでTrueです。

napoleon_numpy_docstring

True to parse NumPy style docstrings. False to disable support for NumPy style docstrings. Defaults to True.

napoleon_include_init_with_doc

True to list __init___ docstrings separately from the class docstring. False to fall back to Sphinx’s default behavior, which considers the __init___ docstring as part of the class documentation. Defaults to False.

If True:

def __init__(self):
    \"\"\"
    This will be included in the docs because it has a docstring
    \"\"\"

def __init__(self):
    # This will NOT be included in the docs
napoleon_include_private_with_doc

True to include private members (like _membername) with docstrings in the documentation. False to fall back to Sphinx’s default behavior. Defaults to False.

If True:

def _included(self):
    """
    This will be included in the docs because it has a docstring
    """
    pass

def _skipped(self):
    # This will NOT be included in the docs
    pass
napoleon_include_special_with_doc

True to include special members (like __membername__) with docstrings in the documentation. False to fall back to Sphinx’s default behavior. Defaults to True.

If True:

def __str__(self):
    """
    This will be included in the docs because it has a docstring
    """
    return unicode(self).encode('utf-8')

def __unicode__(self):
    # This will NOT be included in the docs
    return unicode(self.__class__.__name__)
napoleon_use_admonition_for_examples

True to use the .. admonition:: directive for the Example and Examples sections. False to use the .. rubric:: directive instead. One may look better than the other depending on what HTML theme is used. Defaults to False.

This NumPy style snippet will be converted as follows:

Example
-------
This is just a quick example

If True:

.. admonition:: Example

   This is just a quick example

If False:

.. rubric:: Example

This is just a quick example
napoleon_use_admonition_for_notes

True to use the .. admonition:: directive for Notes sections. False to use the .. rubric:: directive instead. Defaults to False.

注釈

The singular Note section will always be converted to a .. note:: directive.

参考

napoleon_use_admonition_for_examples

napoleon_use_admonition_for_references

True to use the .. admonition:: directive for References sections. False to use the .. rubric:: directive instead. Defaults to False.

参考

napoleon_use_admonition_for_examples

napoleon_use_ivar

True to use the :ivar: role for instance variables. False to use the .. attribute:: directive instead. Defaults to False.

This NumPy style snippet will be converted as follows:

Attributes
----------
attr1 : int
    Description of `attr1`

If True:

:ivar attr1: Description of `attr1`
:vartype attr1: int

If False:

.. attribute:: attr1

   *int*

   Description of `attr1`
napoleon_use_param

True to use a :param: role for each function parameter. False to use a single :parameters: role for all the parameters. Defaults to True.

This NumPy style snippet will be converted as follows:

Parameters
----------
arg1 : str
    Description of `arg1`
arg2 : int, optional
    Description of `arg2`, defaults to 0

If True:

:param arg1: Description of `arg1`
:type arg1: str
:param arg2: Description of `arg2`, defaults to 0
:type arg2: int, optional

If False:

:parameters: * **arg1** (*str*) --
               Description of `arg1`
             * **arg2** (*int, optional*) --
               Description of `arg2`, defaults to 0
napoleon_use_keyword

True to use a :keyword: role for each function keyword argument. False to use a single :keyword arguments: role for all the keywords. Defaults to True.

This behaves similarly to napoleon_use_param. Note unlike docutils, :keyword: and :param: will not be treated the same way - there will be a separate “Keyword Arguments” section, rendered in the same fashion as “Parameters” section (type links created if possible)

参考

napoleon_use_param

napoleon_use_rtype

True to use the :rtype: role for the return type. False to output the return type inline with the description. Defaults to True.

This NumPy style snippet will be converted as follows:

Returns
-------
bool
    True if successful, False otherwise

If True:

:returns: True if successful, False otherwise
:rtype: bool

If False:

:returns: *bool* -- True if successful, False otherwise