Как документировать модуль на Python?

Это просто, вы просто добавляете строку документации вверху модуля.

Для пакетов вы можете задокументировать это в __init__.py. Для модулей вы можете добавить строку документации просто в файл модуля.

Вся информация здесь: http://www.python.org/dev/peps/pep-0257/

Вы делаете это точно так же. Поместите строку в качестве первого оператора в модуле.

Добавьте свою строку документации как первая инструкция в модуле.

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

import foo

# ...

Для пакетов вы можете добавить свою строку документации в __init__.py.

Вот Примеры строк документации Python в стиле Google о том, как можно документировать модуль. В основном это информация о модуле, о том, как его выполнить, а также информация о переменных уровня модуля и список задач.

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

Для пакетов PyPI:

Если вы добавите такие строки документов в свой файл __init__.py, как показано ниже

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

Тогда вы получите это при повседневном использовании функции справки.

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.

Обратите внимание, что моя справка DESCRIPTION запускается тем, что первая строка документации находится в самом верху файла.