123

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

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

4

8 に答える 8

35

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

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

sphinx docstring exampleのこのカットアウトから、*argsと**kwargsは展開されていないままです:

def module_level_function(param1, *args, param2=None, **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以下の *args を明示的にリストすることを試みることができますKeyword Args( docstring セクションを参照):

    """
    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 
        ...
于 2015-08-28T14:22:05.250 に答える
14

ドキュメントに 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=なし)

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(サブプロセス)

私は個人的に、例として 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 の質問に対するこの回答を含めます。

于 2014-01-11T00:30:49.920 に答える
6

他の誰かが有効な構文を探している場合.. 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
于 2013-05-07T13:53:34.860 に答える
-6

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

于 2009-07-16T13:32:54.280 に答える