Python 如何使用Pydoc创建文档？

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

pydoc

：

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

它说

编写了myFile.html

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

# ../myModule/myFile.py

---

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

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

例如，在

myModule/\uuuuu init\uuuuu.py

中：

"""
The mod module
"""

您还需要使用为

myModule/*.py

中的每个文件生成文档

pydoc myModule.thefilename

---

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

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

另一件人们可能会发现有用的事情…请确保在模块名称中去掉“.py”。例如，如果您试图为“original.py”中的'original'生成文档：

---

pydoc-w moduleName

适用于包含一个函数的单个模块。你能试着创建一个简单的例子来重现这一点吗？目录布局和文件内容，以及您在哪里运行哪个命令？如果这是一个愚蠢的问题，请提前道歉，但是您的模块中是否有docstring/等？意思是您的源文件中有运行

pydoc

应该生成的内容吗？对于那些在

.py

文件中自动生成文档的快速搜索查询后到达此页面的用户。这不是

pydoc

的目的。Pydoc适用于您已经编写了文档，并且希望使其美观的情况。我想知道为什么公认的答案没有提供这个小细节！如果不删除.py，它至少在Py3中不起作用。这很有帮助。我还发现，在执行pydoc时，我们需要在同一个目录中。。。i、 例如，我们不能做

pydocdir/prg.py

。我们需要

cd dir

然后执行

pydoc prg.py

。是吗？@abhijithda：事实上，只要包含模块的目录在sys.path中，pydoc就可以找到它。这是最有用的方法，我知道这是关闭的，但至少在Python2.7中，我现在可以做python-m pydoc示例_pydoc（没有.py）并获取我的文档。非常感谢。一旦你有了合适的位置，考虑使用，因为它产生了一个更接近API文档预期的结果。

pydoc myModule.thefilename

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

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

yourcode_dir$ pydoc -w original
wrote original.html