如何在 Python 中记录模块？答案

【问题标题】：How do I document a module in Python?如何在 Python 中记录模块？
【发布时间】：2010-09-07 19:53:56
【问题描述】：

就是这样。如果你想记录一个函数或一个类，你可以在定义之后放一个字符串。例如：

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

但是模块呢？如何记录 file.py 的作用？

【问题讨论】：

看，我刚刚找到了这个：docs.python.org/devguide/documenting.html希望对你有用。

标签： python documentation python-module

【解决方案1】：

将您的文档字符串添加为first statement in the module。

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

import foo

# ...

对于包，您可以将您的文档字符串添加到__init__.py。

【讨论】：

【解决方案2】：

对于包，您可以将其记录在__init__.py。对于模块，您可以简单地在模块文件中添加一个文档字符串。

所有信息都在这里：http://www.python.org/dev/peps/pep-0257/

【讨论】：

【解决方案3】：

这是关于如何记录模块的Example Google Style Python Docstrings。基本上有关于模块的信息，如何执行它以及关于模块级变量和待办事项列表的信息。

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

您的操作方式完全相同。将字符串作为模块中的第一条语句放入。

【讨论】：

这是 eclipse 在创建新模块时自动执行的操作。

【解决方案5】：

很简单，只需在模块顶部添加一个文档字符串即可。

【讨论】：

【解决方案6】：

对于 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 是通过将第一个文档字符串放在文件的最顶部来触发的。

【讨论】：