Wie dokumentiere ich ein Modul in Python?

Question

Das ist es.Wenn Sie eine Funktion oder eine Klasse dokumentieren möchten, fügen Sie direkt nach der Definition einen String ein.Zum Beispiel:

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

Aber wie wäre es mit einem Modul?Wie kann ich dokumentieren, was a file.py tut?

Answer 1

Für die Pakete können Sie es dokumentieren __init__.py.Für die Module können Sie einfach in der Moduldatei einen Docstring hinzufügen.

Alle Informationen gibt es hier: http://www.python.org/dev/peps/pep-0257/

Answer 2

Fügen Sie Ihre Dokumentzeichenfolge als hinzu erste Anweisung im Modul.

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

import foo

# ...

Bei Paketen können Sie Ihre Dokumentzeichenfolge hinzufügen __init__.py.

Answer 3

Hier ist ein Beispiel für Python-Docstrings im Google-Stil wie Module dokumentiert werden können.Im Wesentlichen gibt es Informationen über ein Modul, wie es ausgeführt wird, sowie Informationen über Variablen auf Modulebene und eine Liste von ToDo-Elementen.

"""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

Du machst es genauso.Geben Sie als erste Anweisung im Modul eine Zeichenfolge ein.

Answer 5

Es ist ganz einfach: Sie fügen einfach oben im Modul einen Dokumentstring hinzu.