Il y a un exemple doctstring pour Sphinx dans leur documentation. Plus précisément, ils montrent ce qui suit:
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
Bien que vous ayez posé des questions sur sphinxexplicitement, je voudrais également pointer vers le guide de style Google Python . Leur exemple docstring semble impliquer qu'ils n'appellent pas spécifiquement les kwargs. (other_silly_variable = Aucun)
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 a une question sur la réponse acceptée consistant à référencer la documentation de gestion des sous-processus. Si vous importez un module, vous pouvez voir rapidement les docstrings du module via inspect.getsource.
Un exemple de l'interpréteur python utilisant la recommandation de Silent Ghost:
>>> import subprocess
>>> import inspect
>>> import print inspect.getsource(subprocess)
Bien entendu, vous pouvez également consulter la documentation du module via la fonction d'aide. Par exemple aide (sous-processus)
Je ne suis pas personnellement fan du sous-processus docstring pour kwargs à titre d'exemple, mais comme l'exemple Google, il ne répertorie pas les kwargs séparément, comme indiqué dans l'exemple de documentation Sphinx.
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()
J'inclus cette réponse à la question d'ABB, car il convient de noter que vous pouvez consulter la source ou la documentation de n'importe quel module de cette façon pour obtenir des informations et de l'inspiration pour commenter votre code.