79

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

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

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

4

3 回答 3

106

人们可能会觉得有用的另一件事......确保从你的模块名称中去掉“.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
于 2015-01-11T18:36:48.403 回答
84

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 生成它们时的外观。

于 2012-10-24T13:17:18.833 回答
38

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

例如，在myModule/__init__.py：

"""
The mod module
"""

您还想为myModule/*.py使用中的每个文件生成文档

pydoc myModule.thefilename

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

于 2012-10-24T06:04:38.770 回答