如何使用Pydoc创建文档？

76

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

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

这导致我的shell充满文本，模块中每个文件一行一行，说：

no Python documentation found for '<file_name>'

就像Pydoc试图获取我的文件的文档一样，但是我想自动创建它。我找不到使用Google的优秀教程。有人对使用Pydoc有任何提示吗？

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

python ... -w myModule\myFile.py

它说wrote myFile.html，当我打开它时，它有一行文字说：

# ../myModule/myFile.py

另外，它具有指向我计算机上文件本身的链接，单击该链接即可显示Web浏览器中文件的内容。

— o
source

pydoc -w moduleName对我来说，它适用于具有一个功能的单个模块。您可以尝试创建一个简单的示例来重现吗？目录布局和文件内容，以及在何处运行哪个命令？

— millimoose 2012年

2

如果这是一个愚蠢的问题，请提前道歉，但是您是否有docstrings / etc。在您的模块中？意思是您的源文件中有运行pydoc应该产生的内容吗？

— RocketDonkey 2012年

对于那些在快速搜索查询后如何自动生成文件中的文档后到达此页面的用户.py。那不是pydoc为了什么。Pydoc适用于您已经写过该文档并且想要使其漂亮的文档。

— 在

35

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

例如，在myModule/__init__.py：

"""
The mod module
"""

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

pydoc myModule.thefilename

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

— 米歇尔
source

2

...并且一旦有了文档字符串，请考虑改用pdoc，因为它产生的结果更接近于当今API文档的预期。

— K3 --- rnc

98

人们可能会发现有用的另一件事...确保从模块名称中删除“ .py”。例如，如果您尝试生成“ original.py”中“原始”的文档：

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

yourcode_dir$ pydoc -w original
wrote original.html

— 泰勒
source

4

我不知道为什么接受的答案没有提供这么小的细节！如果不删除.py，则在Py3中至少不会起作用。

— ThinkCode

这有帮助。我还发现，执行pydoc时，我们需要位于同一目录中……也就是说，我们不能这样做pydoc dir/prg.py。我们需要cd dir然后再做pydoc prg.py。是对的吗？

— abhijithda

@abhijithda：实际上，只要包含该模块的目录在sys.path中，pydoc就可以找到它。

— 汤姆·巴伦

这是执行此操作最有用的方法，我知道它已关闭，但至少在python 2.7中，我现在可以执行python -m pydoc Example_Pydoc（不带.py）并获取我的文档。谢谢

— Taku_ '18

79

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

第一个文档字符串提供了使用pydoc创建文档的说明。有一些不同类型的文档字符串的示例，因此您可以查看使用pydoc生成时的外观。

— 兹齐克
source