`sphinx.ext.napoleon` --NumPyおよびGoogleスタイルをサポートする文書文字列¶

モジュールの作者: Rob Ruana

バージョン 1.3 で追加.

概要¶

このような文書文字列を書くのに飽きましたか：

: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

はっきりしていますよね？

ナポレオンは extension Sphinxはこの2つを解析することができます NumPy そして Google スタイルドキュメント文字列-おすすめスタイル Khan Academy それがそうです。

ナポレオンは前プロセッサであり、それは解析されています NumPy そして Google 文書文字列のパターンを設定し，Sphinxがそれらの解析を試みる前にreStrucureTextに変換する.これは，Sphinx処理文書の中間ステップで発生するため，実際のソースコードファイル中のどの文書文字列も修正しない.

スタート¶

事後に. setting up Sphinx あなたのドキュメントを構築するには、ライオン像にナポレオンを起用してください conf.py 書類：：
```
# conf.py

# Add napoleon to the extensions list
extensions = ['sphinx.ext.napoleon']
```
使用 sphinx-apidoc API文書を構築するためには、以下の操作を実行してください。
```
$ sphinx-apidoc -f -o docs/source projectdir
```

文書文字列¶

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.

すべての標準のreStruredTextフォーマットはまだ予想通りに動作しています。

文書文字列部分¶

以下のすべての節のタイトルをサポートします。

Args (alias of Parameters)

Arguments (alias of Parameters)

Attention

Attributes

Caution

Danger

Error

Example

Examples

Hint

Important

Keyword Args (alias of Keyword Arguments)

Keyword Arguments

Methods

Note

Notes

Other Parameters

Parameters

Return (alias of Returns)

Returns

Raise (alias of Raises)

Raises

References

See Also

Tip

Todo

Warning

Warnings (alias of Warning)

Warn (alias of Warns)

Warns

Yield (alias of Yields)

Yields

Google VS NumPy¶

ナポレオンは2つの様式の文書文字列を支持した。 Google そして NumPy それがそうです。この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スタイルは短い簡単な文書文字列を読みやすく、NumPyスタイルは長い深い文書文字列を読みやすい傾向があります。

♪the Khan Academy Googleスタイルをお勧めします。

スタイル間の選択は美学的であることが大きいが、この2つのスタイルは混同すべきではない。あなたのプロジェクトのために一つのスタイルを選択して、それと一致しています。

参考

完全な例については、以下の動作を実行してください。

タイプ注釈¶

PEP 484 Pythonコードにタイプを表示する標準的な方法を紹介した。これは，文書文字列に直接タイプを表すもう1つの選択である.タイプを表す1つの利点は PEP 484 タイプ·チェッカおよびIDEは、静的コード解析を使用することができます。 PEP 484 そして拡張して PEP 526 これは、変数(および属性)を注釈するための類似した方法を導入する。

Python 3タイプの注釈付きGoogle Style：：

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スタイルが含まれています：

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によって支持されていないし、文書にも現れないだろう。

配置¶

以下にナポレオンが使用したすべての設定とそのデフォルト値を示す。Sphinxでこれらの設定を変更することができます conf.py ファイルです。“sphinx.ext.napoleon”が有効にされていることを確認します 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_type_aliases = None
napoleon_attr_annotations = True

napoleon_google_docstring¶: True to Parse(真解析まで) Google style 文書文字列。Falseであれば、Googleスタイル文書文字列のサポートを無効にします。 デフォルトはTrueである.

napoleon_numpy_docstring¶: True to Parse(真解析まで) NumPy style 文書文字列。Falseであれば，NumPyスタイル文書文字列のサポートを無効にする. デフォルトはTrueである.

napoleon_include_init_with_doc¶

True to List(真からリストへ) __init___ クラスdocstringとは別のdocstring.Sphinxのデフォルト行為に戻ると，Falseを返し，そのデフォルト行為を考慮する. __init___ 文書文字列はクラス文書の一部とする. デフォルトはFalseである.

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である場合、プライベートメンバが含まれる(例えば、 _membername )と文書中の文書文字列。Sphinxのデフォルト行為に戻ると，Falseとなる. デフォルトはFalseである.

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である場合、特殊なメンバが含まれる(例えば __membername__ )と文書中の文書文字列。Sphinxのデフォルト行為に戻ると，Falseとなる. デフォルトはTrueである.

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であれば使用する .. admonition:: 指令は適用される 例を引く そして 実例. セグメント化する。使うには .. rubric:: 指示が代わりに。1つは、使用されるHTMLトピックに依存する別のものよりも良く見えるかもしれない。 デフォルトはFalseである.

これが…。 NumPy style コードセグメントは以下のように変換される：

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

Trueなら **

.. admonition:: Example

   This is just a quick example

Falseであれば **

.. rubric:: Example

This is just a quick example

napoleon_use_admonition_for_notes¶: Trueであれば使用する .. admonition:: 以下の対象に対するコマンド 注意事項 セグメント化する。使うには .. rubric:: 指示が代わりに。 デフォルトはFalseである.

注釈

単数数. Note 節はあくまで .. note:: 指令する。

参考

napoleon_use_admonition_for_examples

napoleon_use_admonition_for_references¶: Trueであれば使用する .. admonition:: 以下の対象に対するコマンド 参考文献 セグメント化する。使うには .. rubric:: 指示が代わりに。 デフォルトはFalseである.

参考

napoleon_use_admonition_for_examples

napoleon_use_ivar¶

Trueであれば使用する :ivar: インスタンス変数の役割.使うには .. attribute:: 指示が代わりに。 デフォルトはFalseである.

これが…。 NumPy style コードセグメントは以下のように変換される：

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

Trueなら **

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

Falseであれば **

.. attribute:: attr1

   Description of `attr1`

   :type: int

napoleon_use_param¶

Trueであれば使用する :param: 各関数パラメータの役割.単一を用いるとFalseとなる. :parameters: すべてのパラメータの役割。 デフォルトはTrueである.

これが…。 NumPy style コードセグメントは以下のように変換される：

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

Trueなら **

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

Falseであれば **

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

napoleon_use_keyword¶

Trueであれば使用する :keyword: 各関数キーワードパラメータの役割.単一を用いるとFalseとなる. :keyword arguments: すべてのキーワードの役割。 デフォルトはTrueである.

その行動は napoleon_use_param それがそうです。Docutilsとは異なり :keyword: そして :param: 同じ方法では処理されません-個々の“キーワードパラメータ”部分があり、“パラメータ”部分と同じように提示されます(可能であれば、リンクを入力してください)

参考

napoleon_use_param

napoleon_use_rtype¶

Trueであれば使用する :rtype: タイプの役割を返す。Falseであれば，記述に連結された戻りタイプを出力する. デフォルトはTrueである.

これが…。 NumPy style コードセグメントは以下のように変換される：

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

Trueなら **

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

Falseであれば **

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

napoleon_type_aliases¶

タイプ名を他の名前または参照マッピングに変換します。以下の場合にのみ機能する napoleon_use_param = True それがそうです。 黙認はなし。

使用：：

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

これが…。 NumPy style コードセグメント：：

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

次のようになります

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

バージョン 3.2 で追加.

napoleon_attr_annotations¶: Trueであれば、使用が許可されます PEP 526 クラス中の属性書き込み.ある属性が文書文字列に記録されているが，タイプがなく，クラス体にアノテーションがある場合には，そのタイプを用いる.

バージョン 3.4 で追加.

napoleon_custom_sections¶

含めるべき制約節リストを追加し，解析された節のリストを展開する. 黙認はなし。

これらのエントリは、文字列であってもよく、タプルであってもよく、特に用途に応じて：

カスタマイズされた“汎用”節を作成するには、1つの文字列を渡すだけです。
既存の節のためのエイリアスを作成するためには、エイリアスと元の名前を含むタプルをこの順に渡してください。
PARAMETERSまたはRETURNS節と同様の表示方法を作成するためには、カスタム節名および文字列値“params_style”または“Returns_style”を含むタプルを渡してください。

エントリがただの文字列である場合、汎型部分のタイトルとして解釈される。エントリがタプル/リスト/インデックスコンテナである場合、第1のエントリはセグメントの名前であり、2つ目はシミュレートされるノードキーである。2番目の入力値が“params_style”または“Returns_style”である場合、カスタム節の表示方法は、Parameters節またはReturns節と同様である。

バージョン 1.8 で追加.

バージョン 3.5 で変更: 支持する. params_style そして returns_style

Table of Contents

前のトピックへ

次のトピックへ

`sphinx.ext.napoleon` --NumPyおよびGoogleスタイルをサポートする文書文字列¶

概要¶

スタート¶

文書文字列¶

文書文字列部分¶

Google VS NumPy¶

タイプ注釈¶

配置¶

sphinx.ext.napoleon --NumPyおよびGoogleスタイルをサポートする文書文字列¶

概要¶

スタート¶

文書文字列¶

文書文字列部分¶

Google VS NumPy¶

タイプ注釈¶

配置¶

`sphinx.ext.napoleon` --NumPyおよびGoogleスタイルをサポートする文書文字列¶