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':
Answer from K.S. on Stack Overflowyourcode_dir$ pydoc -w original.py no Python documentation found for 'original.py' yourcode_dir$ pydoc -w original wrote original.html
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
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.
Go to your folder and try:
pydoc -w pydoc_learning
It should generate an .html file
Your first shot should be pydoc --help which is a fairly standard modern way to get help from a command line tool. You can try this with any other commands you have to learn about. When you come to write your own command line tools you would do well to consider adding such an option to your own tools.
Even when a tool does not explicitly support help with either --help or -h (such as pydoc), they sometimes help with option hints when given unsupported input. This is the case with pydoc.
On a unixy system you can also try man (short for manual as in manual page).
I had the same issue and came across this question trying to figure it out. I couldn't figure out how to do it either, so this is my solution. Rather than try to trick pydoc to outputting to a specific location, I'm just generating the documentation in the current directory and moving the files to the location I want.
In my case, the target folder is named 'doc', and the source is located under the 'semlm' directory
mkdir -p doc
pydoc -w `find semlm -name '*.py'`
mv *.html doc
(You should be able to customize the pydoc command as you wish, but this is what worked for me).
I didn't want to type this all out every time so I put it in a Makefile. Here is an excerpt:
.PHONY: doc
doc:
mkdir -p doc
pydoc -w `find semlm -name '*.py'`
mv *.html doc
The .PHONY: doc is needed because the Makefile target has the same name as a folder in the top level directory (i.e. 'doc'). Now I can generate documentation into the doc folder by running:
make doc
Perhaps there is a more elegant way, but this is the best I've found so far.
pydoc -w ...
Write out the HTML documentation for a module to a file in the current directory. If contains a '/', it is treated as a filename; if it names a directory, documentation is written for all the contents.