¿Cómo documento un módulo en Python?

Question

Eso es todo.Si desea documentar una función o una clase, coloque una cadena justo después de la definición.Por ejemplo:

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

Pero ¿qué pasa con un módulo?¿Cómo puedo documentar lo que archivo.py ¿hace?

Answer 1

Para los paquetes, puedes documentarlo en __init__.py.Para los módulos, puede agregar una cadena de documentación simplemente en el archivo del módulo.

Toda la información está aquí: http://www.python.org/dev/peps/pep-0257/

Answer 2

Agregue su cadena de documentación como primera declaración en el módulo.

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

import foo

# ...

Para paquetes, puede agregar su cadena de documentación a __init__.py.

Answer 3

Aquí hay un Ejemplo de cadenas de documentos Python estilo Google sobre cómo se puede documentar el módulo.Básicamente hay información sobre un módulo, cómo ejecutarlo e información sobre las variables a nivel del módulo y la lista de tareas pendientes.

"""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 haces exactamente de la misma manera.Coloque una cadena como primera declaración en el módulo.

Answer 5

Es fácil, simplemente agrega una cadena de documentación en la parte superior del módulo.