如何使用Pydoc创建文档？

Question

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

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

这导致我的shell充满了文本,我的模块中的每个文件都有一行,说:

no Python documentation found for '<file_name>'

这就像Pydoc试图获取我的文件的文档,但我想自动创建它.我找不到使用谷歌的好教程.有没有人有关于如何使用Pydoc的任何提示？

如果我尝试使用一个文件创建文档

python ... -w myModule\myFile.py

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

Answer 1

人们可能会觉得有用的另一件事......确保从模块名称中删除".py".例如,如果你想为生成文档"原始"的" original.py ":

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

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

Answer 3

正如RocketDonkey建议的那样,你的模块本身需要一些文档字符串.

例如,在myModule/__init__.py:

"""
The mod module
"""

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

pydoc myModule.thefilename

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