Question

我试图在 init.py 中记录一个python包，并且我不清楚pydoc如何解析＆＃34;＆＃34;＆＃34;＆＃34;＆＃34;＆＃34;＆＃34;＆＃34;＆＃34;＆＃34;＆＃34;＆＃34;＆＃34;三倍括号＆＃34;＆＃34;＆＃34;评论通过以下方式显示给用户：

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

现在运行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。

希望有所帮助。

Answer 2

看起来第一行包含一个简短的描述（不应超过一行，如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__属性，如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找到更多信息（如作者姓名等）。

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

用于python包的Python pydoc

2 个答案: