How do I document a module in Python?

问题:

That's it. If you want to document a function or a class, you put a string just after the definition. For instance:

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

But what about a module? How can I document what a file.py does?

回答1:

For the packages, you can document it in __init__.py. For the modules, you can add a docstring simply in the module file.

All the information is here: http://www.python.org/dev/peps/pep-0257/

回答2:

Add your docstring as the first statement in the module.

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

import foo

# ...

For packages, you can add your docstring to __init__.py.

回答3:

Here is an Example Google Style Python Docstrings on how module can be documented. Basically there is an information about a module, how to execute it and information about module level variables and list of ToDo items.

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

回答4:

You do it the exact same way. Put a string in as the first statement in the module.

回答5:

It's easy, you just add a docstring at the top of the module.

回答6:

For PyPI Packages:

If you add doc strings like this in your __init__.py file as seen below

"""
Please refer to the documentation provided in the README.md,
which can be found at gorpyter's PyPI URL: https://pypi.org/project/gorpyter/
"""

# <IMPORT_DEPENDENCIES>

def setup():
    """Verify your Python and R dependencies."""

Then you will receive this in everyday usage of the help function.

help(<YOUR_PACKAGE>)

DESCRIPTION
    Please refer to the documentation provided in the README.md,
    which can be found at gorpyter's PyPI URL: https://pypi.org/project/gorpyter/


FUNCTIONS
    setup()
        Verify your Python and R dependencies.

Note, that my help DESCRIPTION is triggered by having that first docstring at the very top of the file.