Come posso documentare un modulo in Python?

Question

Questo è tutto.Se vuoi documentare una funzione o una classe, inserisci una stringa subito dopo la definizione.Ad esempio:

def foo():
    """This function does nothing."""
    pass

Ma che dire di un modulo?Come posso documentare cosa a file.py fa?

Answer 1

Per i pacchi potete documentarlo __init__.py.Per i moduli, puoi aggiungere una docstring semplicemente nel file del modulo.

Tutte le informazioni sono qui: http://www.python.org/dev/peps/pep-0257/

Answer 2

Aggiungi la tua docstring come file prima istruzione nel modulo.

"""
Your module's verbose yet thorough docstring.
"""

import foo

# ...

Per i pacchetti, puoi aggiungere la tua docstring a __init__.py.

Answer 3

Ecco un Esempio di stringhe di documenti Python in stile Google su come documentare il modulo.Fondamentalmente ci sono informazioni su un modulo, come eseguirlo e informazioni sulle variabili a livello di modulo e un elenco di elementi ToDo.

"""Example Google style docstrings.

This module demonstrates documentation as specified by the `Google
Python Style Guide`_. Docstrings may extend over multiple lines.
Sections are created with a section header and a colon followed by a
block of indented text.

Example:
    Examples can be given using either the ``Example`` or ``Examples``
    sections. Sections support any reStructuredText formatting, including
    literal blocks::

        $ python example_google.py

Section breaks are created by resuming unindented text. Section breaks
are also implicitly created anytime a new section starts.

Attributes:
    module_level_variable1 (int): Module level variables may be documented in
        either the ``Attributes`` section of the module docstring, or in an
        inline docstring immediately following the variable.

        Either form is acceptable, but the two should not be mixed. Choose
        one convention to document module level variables and be consistent
        with it.

Todo:
    * For module TODOs
    * You have to also use ``sphinx.ext.todo`` extension

.. _Google Python Style Guide:   
http://google.github.io/styleguide/pyguide.html

"""

module_level_variable1 = 12345

def my_function():   
    pass 
... 
...

Answer 4

Lo fai esattamente nello stesso modo.Inserisci una stringa come prima istruzione nel modulo.

Answer 5

È semplice, basta aggiungere una docstring nella parte superiore del modulo.