如何使用Pydoc创建文档？

Question

我正试图用我的模块创建一个文档。我使用Python 3.2.3在Windows 7的命令行中使用了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

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

Answer 1

pydoc非常适合生成文档，但文档必须首先编写。你的源代码中必须有RocketDonkey在评论中提到的docstring：

"""
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创建文档的说明。这里有不同类型的docstring的示例，因此您可以看到它们在使用pydoc生成时的外观。

Answer 2

正如RocketDonkey所建议的，模块本身需要一些docstring。

例如，在myModule/__init__.py中：

"""
The mod module
"""

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

pydoc myModule.thefilename

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

Answer 3

人们可能会发现另一件有用的事情…确保在你的模块名中去掉“.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