问题
I'm trying to create a document out of my module. I used pydoc from the command-line in Windows 7 using Python 3.2.3:
python "<path_to_pydoc_>\pydoc.py" -w myModule
This led to my shell being filled with text, one line for each file in my module, saying:
no Python documentation found for '<file_name>'
It's as if Pydoc's trying to get documentation for my files, but I want to autocreate it. I couldn't find a good tutorial using Google. Does anyone have any tips on how to use Pydoc?
If I try to create documentation from one file using
python ... -w myModule\myFile.py
it says wrote myFile.html, and when I open it, it has one line of text saying:
# ../myModule/myFile.py
Also, it has a link to the file itself on my computer, which I can click and it shows what's inside the file on my web browser.
回答1:
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.
回答2:
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
回答3:
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.
来源：https://stackoverflow.com/questions/13040646/how-do-i-create-documentation-with-pydoc