La directive générale que vous cherchez est juste PEP257 dans ce que vous avez cité, peut-être vous avez juste besoin de le voir en action.
Votre fonction est un bon candidat pour une docstring une ligne (« vraiment des cas évidents »):
def script_running(self, script):
"""Check if the script is running."""
Habituellement, si vous dites qu'une fonction est de vérifier quelque chose, cela signifie qu'il va revenir True ou False, mais si vous le souhaitez, vous pouvez être plus précis:
def script_running(self, script):
"""Return True if the script is running, False otherwise."""
encore une fois en une seule ligne.
Je changerais probablement aussi le nom de votre fonction, car il n'y a pas besoin de souligner ce que la fonction fonctionne dans son nom (un script). Un nom de fonction doit être quelque chose de doux, court et significatif sur ce que fait la fonction. Probablement, je vais aller avec:
def check_running(self, script):
"""Return True if the script is running, False otherwise."""
Parfois, par tout le codage nom_de_la_fonction-imagination est fatigué , mais vous devriez quand même essayer de faire de votre mieux.
Pour un exemple multiligne, laissez-moi empruntons docstring du google guidelines:
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.
"""
Cela pourrait être une façon de « résumer son comportement et documenter ses arguments, la valeur de retour (s), les effets secondaires, exceptions levées et restrictions sur le moment où elles peuvent être appelées (le cas échéant) ".
Vous pourriez également être intéressé à regarder ce example of pypi project qu'il est censé être documenté avec Sphinx.
Mes 2 cents: lignes directrices sont destinées à vous donner une idée de ce que vous devriez et ne devriez pas faire, mais ils ne sont pas des règles strictes que vous devez suivre aveuglément. Donc, à la fin, choisissez ce que vous ressentez pour être meilleur.
Je voudrais éclaircir quelque chose qui a été dit dans une autre réponse à frapper la Longueur maximale avec un docstring.
PEP8 vous dit de "Limite toutes les lignes à un maximum de 79 caractères" même si au final tout le monde ne 80.
Ce sont 80 charachters:
--------------------------------------------------------------------------------
Et cela peut être un cas limite où un peu longue phrase est tout ce que vous avez vraiment besoin:
def my_long_doc_function(arg1, arg2):
"""This docstring is long, it's a little looonger than the 80 charachters
limit.
"""
est comme une ligne docstring, ce qui signifie que pour les cas vraiment évidents, mais sur votre éditeur (avec la limite 80 charachter) est sur plusieurs lignes.