Python python 个软件包的 pydoc

Question

我正在尝试在 init.py 中记录一个 python 包，我不清楚 pydoc 如何解析 """triple bracketed" "" 评论通过以下方式显示给用户：

>>> help(package)

或

$ pydoc package

如何解析注释以在 pydoc 输出的 NAME 和 DESCRIPTION 部分提供内容？是否还有其他部分我可以填充，例如示例？

Answer 1

让我们考虑一下这个虚拟包：

./whatever
├── __init__.py
├── nothing
│   └── __init__.py
└── something.py

在 ./whatever/__init__.py 中我们有：

"""
This is whatever help info.

This is whatever description

EXAMPLES:
    ...
"""

__version__ = '1.0'

variable = 'variable'

现在运行pythonshell:

➜  ~ python
Python 2.7.12 (default, Jul  1 2016, 15:12:24) 
[GCC 5.4.0 20160609] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import whatever
>>> help(whatever)

输出为：

NAME
    whatever - This is whatever help info.

FILE
    /home/el/whatever/__init__.py

DESCRIPTION
    This is whatever description

    EXAMPLES:
        ...

PACKAGE CONTENTS
    nothing (package)
    something

DATA
    __version__ = '1.0'
    variable = 'variable'

VERSION
    1.0

您可以在描述部分提供示例。所以在 ./whatever/__init__.py。

希望对您有所帮助。

Answer 2

第一行好像是一段简短的描述（不能超过一行，如PEP 257所述），会放在名字后面；后跟一个空行，然后是一个段落，用于在 DESCRIPTION 部分提供内容。

所以，例如，如果你在 just_to_see/__init__.py 中有这个（带有模块的简单示例）：

"""A short description

A longer description on several lines etc.
blablabla etc."""

def a_function():
    """
    An interesting introductive comment.

    Some more explanations.
    """
    pass

（请注意，文档字符串可以在其他地方，例如在 __doc__ 属性中，如 here 所述）

然后 pydoc3.4 just_to_see/__init__.py 将输出：

Help on module __init__:

NAME
    __init__ - A short description

DESCRIPTION
    A longer description on several lines etc.
    blablabla etc.

FUNCTIONS
    a_function()
        An interesting introductive comment.

        Some more explanations.

FILE
    /home/nico/temp/just_to_see/__init__.py

如果您的软件包已安装（例如在虚拟环境中），pydoc 可以从其 setup.py 中找到更多信息（如作者姓名等）。

不确定如何触发示例部分。在标准 python 库的 pydoc 输出中找不到示例部分的任何示例（但我还没有全部浏览）。也许您可以在包的文档字符串的长描述中添加这样的部分。但是因为他们似乎没有在标准库中这样做，也许它不是放置示例的正确位置？

Python python 个软件包的 pydoc

Python pydoc for python packages

python

pydoc