web-dev-qa-db-ja.com

** kwargsパラメータを文書化する正しい方法は何ですか？

sphinx とautodocプラグインを使用して、PythonモジュールのAPIドキュメントを生成します。特定のパラメーターを適切にドキュメント化する方法はわかりますが、例を見つけることができません。 **kwargsパラメータ。

これらを文書化する明確な方法の良い例はありますか？

pythondocumentationpython-sphinx
77
jkp

subprocess- moduleのドキュメント は良い例だと思います。 top/parent class のすべてのパラメーターの完全なリストを提供します。次に、そのリストを参照して、他のすべての**kwargs。

15
SilentGhost

この質問を見つけた後、私は次のことに決めました。これは有効なSphinxであり、かなりうまく機能します。

def some_function(first, second="two", **kwargs):
    r"""Fetches and returns this thing

    :param first:
        The first parameter
    :type first: ``int``
    :param second:
        The second parameter
    :type second: ``str``
    :param \**kwargs:
        See below

    :Keyword Arguments:
        * *extra* (``list``) --
          Extra stuff
        * *supplement* (``dict``) --
          Additional content

    """

r"""..."""は、これを「生」のdocstringにして、\*をそのまま保持するために必要です（Sphinxが "強調"の開始ではなく、リテラル*として取得するため）。

選択された書式設定（括弧で囲まれたタイプとmダッシュで区切られた説明を含む箇条書きリスト）は、Sphinxが提供する自動書式設定と一致させるためのものです。

「キーワード引数」セクションをデフォルトの「パラメータ」セクションのように見せるためにこの作業を行ったら、最初から独自のパラメータセクションをロールする方が簡単なようです（他のいくつかの回答に従って）しかし、これは概念実証として、すでにSphinxを使用している場合に補足**kwargsの見栄えを良くする1つの方法です。

36
quornian

Sphinxによって解析されるGoogleスタイルのドキュメント文字列

免責事項：テストされていません。

sphinx docstring example のこのカットアウトから、*argsと**kwargsが残りますunexpanded：

def module_level_function(param1, param2=None, *args, **kwargs):
    """
    ...

    Args:
        param1 (int): The first parameter.
        param2 (Optional[str]): The second parameter. Defaults to None.
            Second line of description should be indented.
        *args: Variable length argument list.
        **kwargs: Arbitrary keyword arguments.

私はsuggestをコンパクトにするために次の解決策をします：

    """
    Args:
        param1 (int): The first parameter.
        param2 (Optional[str]): The second parameter. Defaults to None.
            Second line of description should be indented.
        *param3 (int): description
        *param4 (str): 
        ...
        **key1 (int): description 
        **key2 (int): description 
        ...

**key引数にはOptionalが必要ないことに注意してください。

それ以外の場合、Other Parametersの下の* argsと**kwargsの下のKeyword Argsを明示的にリストしようとすることができます（参照解析済み セクション ）：

    """
    Args:
        param1 (int): The first parameter.
        param2 (Optional[str]): The second parameter. Defaults to None.
            Second line of description should be indented.

    Other Parameters:
        param3 (int): description
        param4 (str): 
        ...

    Keyword Args:
        key1 (int): description 
        key2 (int): description 
        ...
18
Oleg

Sphinxのドキュメントには doctstringの例 があります。具体的には、次のことを示しています。

def public_fn_with_googley_docstring(name, state=None):
"""This function does something.

Args:
   name (str):  The name to use.

Kwargs:
   state (bool): Current state to be in.

Returns:
   int.  The return code::

      0 -- Success!
      1 -- No good.
      2 -- Try again.

Raises:
   AttributeError, KeyError

A really great idea.  A way you might use me is

>>> print public_fn_with_googley_docstring(name='foo', state=None)
0

BTW, this always returns 0.  **NEVER** use with :class:`MyPublicClass`.

"""
return 0

sphinx について明示的に尋ねましたが、私は Google Python Style Guide も指摘します。彼らのdocstringの例は、特にkwargsを呼び出さない（other_silly_variable = None）

def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
"""Fetches rows from a Bigtable.

Retrieves rows pertaining to the given keys from the Table instance
represented by big_table.  Silly things may happen if
other_silly_variable is not None.

Args:
    big_table: An open Bigtable Table instance.
    keys: A sequence of strings representing the key of each table row
        to fetch.
    other_silly_variable: Another optional variable, that has a much
        longer name than the other args, and which does nothing.

Returns:
    A dict mapping keys to the corresponding table row data
    fetched. Each row is represented as a Tuple of strings. For
    example:

    {'Serak': ('Rigel VII', 'Preparer'),
     'Zim': ('Irk', 'Invader'),
     'Lrrr': ('Omicron Persei 8', 'Emperor')}

    If a key from the keys argument is missing from the dictionary,
    then that row was not found in the table.

Raises:
    IOError: An error occurred accessing the bigtable.Table object.
"""
pass

A-B-Bには、サブプロセス管理ドキュメントを参照することで受け入れられている答えについての質問があります。モジュールをインポートすると、inspect.getsourceを介してモジュールのdocstringsをすばやく確認できます。

Silent Ghostの推奨事項を使用したpythonインタープリターの例：

>>> import subprocess
>>> import inspect
>>> import print inspect.getsource(subprocess)

もちろん、ヘルプ機能を使用してモジュールのドキュメントを表示することもできます。たとえば、help（subprocess）

私は個人的にはkwargsのサブプロセスdocstringの例としては好きではありませんが、Googleの例のように、Sphinxのドキュメント例に示されているようにkwargsを個別にリストしません。

def call(*popenargs, **kwargs):
"""Run command with arguments.  Wait for command to complete, then
return the returncode attribute.

The arguments are the same as for the Popen constructor.  Example:

retcode = call(["ls", "-l"])
"""
return Popen(*popenargs, **kwargs).wait()

A-B-Bの質問へのこの回答は、モジュールのソースまたはドキュメントをこの方法でレビューして、コードにコメントするための洞察とインスピレーションを得ることができることに注意する価値があるため、この回答を含めています。

8
binarysubstrate

他の誰かが有効な構文を探している場合.. docstringの例を次に示します。これは私がやった方法であり、あなたにとって有用であることを願っていますが、特に何かに準拠していると主張することはできません。

def bar(x=True, y=False):
    """
    Just some silly bar function.

    :Parameters:
      - `x` (`bool`) - dummy description for x
      - `y` (`string`) - dummy description for y
    :return: (`string`) concatenation of x and y.
    """
    return str(x) + y

def foo (a, b, **kwargs):
    """
    Do foo on a, b and some other objects.

    :Parameters:
      - `a` (`int`) - A number.
      - `b` (`int`, `string`) - Another number, or maybe a string.
      - `\**kwargs` - remaining keyword arguments are passed to `bar`

    :return: Success
    :rtype: `bool`
    """
    return len(str(a) + str(b) + bar(**kwargs)) > 20
4
m01

これは、使用するドキュメントのスタイルによって異なりますが、 numpydoc スタイルを使用している場合は、**kwargs使用 Other Parameters 。

たとえば、次の定足数の例：

def some_function(first, second="two", **kwargs):
    """Fetches and returns this thing

    Parameters
    ----------
    first : `int`
        The first parameter
    second : `str`, optional
        The second parameter

    Other Parameters
    ----------------
    extra : `list`, optional
        Extra stuff. Default ``[]``.
    suplement : `dict`, optional
        Additional content. Default ``{'key' : 42}``.
    """

特に、kwargsのデフォルトを指定することをお勧めします。これらは関数シグネチャからは明らかではないためです。

2
Jonas Adler