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

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

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

subprocess-moduleのドキュメントが良い例だと思います。トップ/親クラスのすべてのパラメータの完全なリストを提供します。次に、他のすべてのについて、そのリストを参照してください**kwargs。

この質問を見つけた後、私は次のことに同意しました。これは有効な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"""..."""は、これを「生の」ドキュメント文字列にしてその\*ままにするために必要です（Sphinx *が「強調」の始まりではなくリテラルとしてピックアップするため）。

選択されたフォーマット（括弧で囲まれたタイプとmダッシュで区切られた説明を含む箇条書き）は、Sphinxによって提供される自動フォーマットと一致させるためのものです。

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

Sphinxが解析するGoogleスタイルのドキュメント文字列

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

このスフィンクスdocstringの例のカットアウトから、*argsおよび**kwargsは展開されないままになっています。

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.

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

    """
    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 
        ...

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

それ以外の場合は、明示的に下の*引数を一覧表示しようとすることができますOther Parametersし、**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 
        ...

ドキュメントには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

あなたは尋ねましたが スフィンクス明示的に、私は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

ABBは、サブプロセス管理ドキュメントを参照することの承認された回答について質問があります。モジュールをインポートすると、inspect.getsourceでモジュールのドキュメント文字列をすばやく確認できます。

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()

コードにコメントするための洞察とインスピレーションを得るためにモジュールのソースまたはドキュメントをこの方法で確認できることは注目に値するので、ABBの質問に対するこの回答を含めています。

他の誰かがいくつかの有効な構文を探している場合.. 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

これは、使用するドキュメントのスタイルによって異なりますが、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のデフォルトを指定することをお勧めします。

これをnumpydocスタイルで行う方法を探している場合は、タイプを指定せずにパラメーターセクションで単に言及**kwargsすることができます- スフィンクス拡張ナポレオンのnumpydocの例とパンダドキュメンテーションスプリント2018のdocstringガイドで示されています。

ここで私が見つかり例ですLSST開発者ガイド非常によくどうあるべきかを説明記述の**kwargsパラメータは：

def demoFunction(namedArg, *args, flag=False, **kwargs):
    """Demonstrate documentation for additional keyword and
    positional arguments.

    Parameters
    ----------
    namedArg : `str`
        A named argument that is documented like always.
    *args : `str`
        Additional names.

        Notice how the type is singular since the user is expected to pass individual
        `str` arguments, even though the function itself sees ``args`` as an iterable
        of `str` objects).
    flag : `bool`
        A regular keyword argument.
    **kwargs
        Additional keyword arguments passed to `otherApi`.

        Usually kwargs are used to pass parameters to other functions and
        methods. If that is the case, be sure to mention (and link) the
        API or APIs that receive the keyword arguments.

        If kwargs are being used to generate a `dict`, use the description to
        document the use of the keys and the types of the values.
    """

または、@ Jonas Adlerの提案に基づいて構築し、セクションとその説明をセクションに配置した**kwargsOther Parameters方がよいと思います。matplotlib ドキュメントガイドのこの例でも同じことを示唆しています。