У їхній документації наведено приклад для Sphinx. Зокрема, вони показують наступне:
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 . Їхній приклад документації, здається, означає, що вони не називають кваргів спеціально. (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.
Приклад з інтерпретатора python, що використовує рекомендацію Silent Ghost:
>>> import subprocess
>>> import inspect
>>> import print inspect.getsource(subprocess)
Звичайно, ви також можете переглянути документацію до модуля за допомогою довідкової функції. Наприклад довідка (підпроцес)
Я особисто не шанувальник підпроцесу документації для kwargs як приклад, але, як і приклад Google, він не перелічує kwargs окремо, як показано в прикладі документації 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()
Я включаю цю відповідь на питання АББ, оскільки варто зазначити, що ви можете переглянути джерело будь-якого модуля або документацію таким чином, щоб отримати розуміння та натхнення для коментування вашого коду.