如何使用 Pydoc 创建文档？

Question

我正在尝试从我的模块中创建一个文档。我在 Windows 7 中使用 Python 3.2.3 从命令行使用了

pydoc

：

python "<path_to_pydoc_>\pydoc.py" -w myModule

这导致我的 shell 充满了文本，模块中的每个文件一行，内容如下：

no Python documentation found for '<file_name>'

就好像 Pydoc 试图获取我的文件的文档，但我想自动创建它。我无法使用 Google 找到好的教程。有人对如何使用 Pydoc 有任何建议吗？

如果我尝试使用

从一个文件创建文档

python ... -w myModule\myFile.py

它写着

wrote myFile.html

，当我打开它时，它有一行文字：

# ../myModule/myFile.py

此外，它还有一个指向我计算机上的文件本身的链接，我可以单击该链接，它会在我的网络浏览器上显示文件内的内容。

Answer 1

人们可能会发现有用的另一件事......确保从模块名称中删除“.py”。例如，如果您尝试在 'original.py' 中生成 'original' 的文档：

yourcode_dir$ pydoc -w original.py
no Python documentation found for 'original.py'

yourcode_dir$ pydoc -w original
wrote original.html

Answer 2

pydoc 非常适合生成文档，但必须首先编写文档。正如 RocketDonkey 在评论中提到的那样，您的源代码中必须包含文档字符串：

"""
This example module shows various types of documentation available for use
with pydoc.  To generate HTML documentation for this module issue the
command:

    pydoc -w foo

"""

class Foo(object):
    """
    Foo encapsulates a name and an age.
    """
    def __init__(self, name, age):
        """
        Construct a new 'Foo' object.

        :param name: The name of foo
        :param age: The ageof foo
        :return: returns nothing
        """
        self.name = name
        self.age = age

def bar(baz):
    """
    Prints baz to the display.
    """
    print baz

if __name__ == '__main__':
    f = Foo('John Doe', 42)
    bar("hello world")

第一个文档字符串提供了使用 pydoc 创建文档的说明。有不同类型的文档字符串的示例，因此您可以看到它们使用 pydoc 生成时的外观。

Answer 3

正如 RocketDonkey 所建议的，你的模块本身需要有一些文档字符串。

例如，在

myModule/__init__.py

中：

"""
The mod module
"""

您还想使用

 为 

myModule/*.py

中的每个文件生成文档

pydoc myModule.thefilename

确保生成的文件与主模块文档文件中引用的文件匹配。

Answer 4

适用于 Windows7：

python -m pydoc -w my_module

Answer 5

PyDoc 根据您在代码中编写的 docstrings 读取并生成文档。文档字符串只是用三引号括起来的注释，告诉其他人代码的作用、参数是什么或函数返回什么。 我建议两种方法来做到这一点：

从代码编辑器内部生成 HTML 文档的一种方法是 import pydoc 并在最后使用 pydoc.writedoc('name_of_my_module') 。这会在同一目录中生成 name_of_my_module.html。

import pydoc

def add(x, y):
"""
    Params:
      x and b are numbers (int or float)
    Returns: 
      the sum of x and y.
"""
    return x + y

pydoc.writedoc('my_module')

或者，您可以删除 import pydoc 和最后一行，转而使用命令行 python -m pydoc -w my_module

要了解更多信息，您可以阅读以下文章： https://pythonology.eu/how-to-use-pydoc-to-generate-documentation-in-python/