如何使用Pydoc创建文档？

Question

我正在尝试在我的模块之外创建一个文档。我在使用Python3.2.3的Windows7中从命令行使用了pydoc：

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

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

no Python documentation found for '<file_name>'

这就像Pydoc试图为我的文件获取文档一样，但我想自动创建它。我找不到一个好的使用谷歌的教程。有没有人有关于如何使用Pydoc的建议？

如果我尝试使用以下命令从一个文件创建文档

python ... -w myModule\myFile.py

它显示为wrote myFile.html，当我打开它时，它有一行文本说：

# ../myModule/myFile.py

此外，它在我的电脑上有一个指向文件本身的链接，我可以点击它，它会在我的web浏览器上显示文件中的内容。

Answer 1

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

例如，在myModule/__init__.py中

"""
The mod module
"""

您还需要使用以下命令为myModule/*.py中的每个文件生成文档

pydoc myModule.thefilename

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

Answer 2

另一件事是人们可能会发现useful...make一定会在你的模块名称中去掉".py“。例如，如果您试图在'original.py'：中为的“原始”生成文档

yourcode_dir$ pydoc -w original.py未找到'original.py‘的Python文档yourcode_dir$ pydoc -w原始编写的original.html

Answer 3

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")

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