如何使用 Pydoc 创建文档？

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

此外，它还有一个链接到我电脑上的文件本身，我可以点击它，它显示了我的网页浏览器上的文件内容。

165999 次浏览
小开
最佳答案

As RocketDonkey suggested, your module itself needs to have some docstrings.

For example, in myModule/__init__.py:

"""
The mod module
"""

You'd also want to generate documentation for each file in myModule/*.py using

pydoc myModule.thefilename

to make sure the generated files match the ones that are referenced from the main module documentation file.

小开

pydoc is fantastic for generating documentation, but the documentation has to be written in the first place. You must have docstrings in your source code as was mentioned by RocketDonkey in the comments:

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

The first docstring provides instructions for creating the documentation with pydoc. There are examples of different types of docstrings so you can see how they look when generated with pydoc.

小开

Another thing that people may find useful...make sure to leave off ".py" from your module name. For example, if you are trying to generate documentation for 'original' in 'original.py':

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


yourcode_dir$ pydoc -w original
wrote original.html
小开

works on windows7:

python -m pydoc -w my_module

提交答案