Quelle est la bonne façon de documenter un paramètre kwargs ?

Question

J'utilise Sphinx et l'extension autodoc pour générer de la documentation API pour mes modules Python. Bien que je puisse voir comment bien documenter des paramètres spécifiques, je ne trouve pas d'exemple de comment documenter un paramètre **kwargs.

Quelqu'un a-t-il un bon exemple d'un moyen clair de les documenter ?

Answer 1

Si quelqu'un d'autre cherche une syntaxe valide... Voici un exemple de docstring. C'est comme ça que je l'ai fait, j'espère que c'est utile pour vous, mais je ne peux pas prétendre qu'il est conforme à quoi que ce soit en particulier.

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