Hay un ejemplo de doctstring para Sphinx en su documentación. Concretamente muestran lo siguiente:
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
Aunque preguntaste sobre esfingeexplícitamente, también señalaría la Guía de estilo de Google Python . Su ejemplo de cadena de documentos parece implicar que no llaman específicamente a los kwargs. (other_silly_variable = Ninguno)
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 tiene una pregunta sobre la respuesta aceptada de hacer referencia a la documentación de gestión de subprocesos. Si importa un módulo, puede ver rápidamente las cadenas de documentos del módulo a través de inspect.getsource.
Un ejemplo del intérprete de Python que utiliza la recomendación de Silent Ghost:
>>> import subprocess
>>> import inspect
>>> import print inspect.getsource(subprocess)
Por supuesto, también puede ver la documentación del módulo a través de la función de ayuda. Por ejemplo ayuda (subproceso)
Personalmente, no soy un fanático de la cadena de documentos de subproceso para kwargs como ejemplo, pero al igual que el ejemplo de Google, no enumera los kwargs por separado, como se muestra en el ejemplo de documentación de 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()
Incluyo esta respuesta a la pregunta de ABB porque vale la pena señalar que puede revisar la fuente o la documentación de cualquier módulo de esta manera para obtener información e inspiración para comentar su código.