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

モジュールの作者: Rob Ruana

Added in version 1.3.

概要¶

以下のような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 is great, but it creates visually dense, hard to read docstrings. Compare the jumble above to the same thing rewritten according to the 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 is a extension that enables Sphinx to parse both NumPy and Google style docstrings - the style recommended by Khan Academy.

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

はじめに¶

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

# conf.py

# Add napoleon to the extensions list
extensions = ['sphinx.ext.napoleon']

Use sphinx-apidoc to build your API documentation:
```
$ 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 (Parameters の別名)
Arguments (Parameters の別名)
Attention
Attributes
Caution
Danger
Error
Example
Examples
Hint
Important
Keyword Args (Keyword Argumentsの別名)
Keyword Arguments
Methods
Note
Notes
Other Parameters
Parameters
Return (Returns の別名)
Returns
Raise (alias of Raises)
Raises
References
See Also
Tip
Todo
Warning
Warnings (Warning の別名)
Warn (alias of Warns)
Warns
Yield (Yieldsの別名)
Yields

Google vs NumPy¶

Napoleon supports two styles of docstrings: Google and NumPy. The main difference between the two styles is that Google uses indentation to separate sections, whereas NumPy uses underlines.

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で読みやすくなります。

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

参考

For complete examples:

型アノテーション¶

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. PEP 484 was then extended by PEP 526 which introduced a similar way to annotate variables (and attributes).

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

class Class:
    """Summary line.

    Extended description of class

    Attributes:
        attr1: Description of attr1
        attr2: Description of attr2
    """

    attr1: int
    attr2: str

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

class Class:
    """Summary line.

    Extended description of class

    Attributes:
        attr1 (int): Description of attr1
        attr2 (str): Description of attr2
    """

注釈

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

設定¶

Listed below are all the settings used by napoleon and their default values. These settings can be changed in the Sphinx conf.py file. Make sure that "sphinx.ext.napoleon" is enabled in conf.py:

# conf.py

# Add any Sphinx extension module names here, as strings
extensions = ['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_preprocess_types = False
napoleon_type_aliases = None
napoleon_attr_annotations = 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

   Description of `attr1`

   :type: int

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: :class:`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

napoleon_preprocess_types¶: True to convert the type definitions in the docstrings as references. Defaults to False.

Added in version 3.2.1.

バージョン 3.5 で変更: Do preprocess the Google style docstrings also.

napoleon_type_aliases¶

A mapping to translate type names to other names or references. Works only when napoleon_use_param = True. Defaults to None.

With:

napoleon_type_aliases = {
    "CustomType": "mypackage.CustomType",
    "dict-like": ":term:`dict-like <mapping>`",
}

This NumPy style snippet:

Parameters
----------
arg1 : CustomType
    Description of `arg1`
arg2 : dict-like
    Description of `arg2`

becomes:

:param arg1: Description of `arg1`
:type arg1: mypackage.CustomType
:param arg2: Description of `arg2`
:type arg2: :term:`dict-like <mapping>`

Added in version 3.2.

napoleon_attr_annotations¶: True to allow using PEP 526 attributes annotations in classes. If an attribute is documented in the docstring without a type and has an annotation in the class body, that type is used.

Added in version 3.4.

napoleon_custom_sections¶

Add a list of custom sections to include, expanding the list of parsed sections. Defaults to None.

The entries can either be strings or tuples, depending on the intention:

To create a custom "generic" section, just pass a string.
To create an alias for an existing section, pass a tuple containing the alias name and the original, in that order.
To create a custom section that displays like the parameters or returns section, pass a tuple containing the custom section name and a string value, "params_style" or "returns_style".

If an entry is just a string, it is interpreted as a header for a generic section. If the entry is a tuple/list/indexed container, the first entry is the name of the section, the second is the section key to emulate. If the second entry value is "params_style" or "returns_style", the custom section will be displayed like the parameters section or returns section.

Added in version 1.8.

バージョン 3.5 で変更: Support params_style and returns_style

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

概要¶

はじめに¶

Docstrings¶

Docstring Sections¶

Google vs NumPy¶

型アノテーション¶

設定¶

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