Общее руководство, которое вы ищете, прямо в PEP257 в том, что вы цитировали, возможно, вам просто нужно увидеть его в действии.
Ваша функция является хорошим кандидатом на одну строку документации ( "действительно очевидные случаи" ):
def script_running(self, script):
"""Check if the script is running."""
Обычно, если вы говорите, что функция что-то проверяет, это означает, что она вернет True или False, но если вам нравится, вы можете указать более конкретно:
def script_running(self, script):
"""Return True if the script is running, False otherwise."""
Еще раз все в одной строке.
Возможно, я бы также изменил имя вашей функции, потому что нет необходимости подчеркивать, что функция работает в своем названии (сценарий). Имя функции должно быть чем-то приятным, коротким и осмысленным в отношении того, что делает функция. Вероятно, я пойду с:
def check_running(self, script):
"""Return True if the script is running, False otherwise."""
Иногда функция-имя-воображение устала от всего кодирования, но вы все равно должны попытаться сделать все возможное.
Для примера с несколькими строками позвольте мне позаимствовать строку документации из правил Google :
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.
"""
Это может быть один из способов "обобщить его поведение и задокументировать его аргументы, возвращаемые значения, побочные эффекты, возникшие исключения и ограничения, когда он может быть вызван (все, если применимо)" .
Вам также может быть интересно посмотреть на пример проекта pypi , который предполагается задокументировать с помощью Sphinx .
Мои 2 цента: Правила предназначены для того, чтобы дать вам представление о том, что вы должны и чего не должны делать, но они не являются строгими правилами , которым вы должны слепо следовать. Поэтому в конце выберите, что вы чувствуете, чтобы быть лучше.
Я хотел бы прояснить кое-что, что было сказано в другом ответе о попадании Максимальная длина строки строкой документации.
PEP8 говорит вам «Ограничить все строки максимум 79 символами» , хотя в конце каждый делает 80.
Это 80 символов:
--------------------------------------------------------------------------------
И это может быть крайний случай, когда немного длинное одно предложение - это все, что вам действительно нужно:
def my_long_doc_function(arg1, arg2):
"""This docstring is long, it's a little looonger than the 80 charachters
limit.
"""
Похож на однострочную строку документации, что означает для действительно очевидных случаев , но в вашем редакторе (с пределом в 80 символов) на нескольких строках.