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つのスタイルは混用するべきではありません。ご自身のプロジェクトでひとつのスタイルを選び、一貫させましょう。

Type Annotations

PEP 484 introduced a standard way to express types in Python code. This is an alternative to expressing types directly in docstrings. One benefit of expressing types according to PEP 484 is that type checkers and IDEs can take advantage of them for static code analysis.

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 aren’t currently supported by Sphinx and won’t show up in the docs.

Configuration

以下のリストは、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