1

我正在尝试在init.py中记录一个 python 包，但我不清楚 pydoc 如何解析 """三方括号""" 注释以通过以下方式显示给用户：

>>> help(package)

或者

$ pydoc package

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

4

2 回答 2

2

让我们考虑这个虚拟包：

./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'

现在运行python shell：

➜  ~ 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.

希望有帮助。

于 2016-09-08T15:20:37.903 回答
1

看起来第一行包含一个简短的描述（不应超过一行，如PEP 257中所述），将放在名称之后；后跟一个空行，然后是一个段落，用于在说明部分提供内容。

因此，例如，如果您有这个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__属性中，如此处所述）

然后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（但我还没有全部浏览）。也许您可以在包的文档字符串的长描述中添加这样的部分。但由于他们似乎没有在标准库中这样做，也许这不是放置示例的正确位置？

于 2016-09-08T15:25:19.617 回答