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
I have found that the pydoc documentation for libraries is often far less detailed than the online documentation. It drives me crazy that I cannot quickly review documentation via the commandline. I try to, but always end up having to jump onto the web for the full documentation. Is there a reason for this discrepancy?
I have a lot of experience with Perl where, in general, the perldoc documentation and any online documentation match, because they are generated from the same source. Is there a way to achieve that with Python?
python - How do I create documentation with Pydoc? - Stack Overflow
Pydoc / Documentation Module
python - What does the Pydoc module do? - Stack Overflow
pydoc vs online documentation
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.
Pydoc is a help / documentation module for Python.
Use this on your Windows terminal to understand what a function in python does :
python -m pydoc <function>
eg.
python -m pydoc raw_input
If the documentation for a particular function is very long, use 'q' to get out of it.
e.g. in case of
python -m pydoc Tkinter
Pydoc module in Python can be used to generate documentation in the form of html pages or even on the console
python -m pydoc
This command gives options like view the pydoc for a file, -k search for different libraries, -p allows to open a page in web browser to view python packages, -g provides a graphical interface for looking documentation, -w writes an html output. Below are the sample commands that you can fire for testing.
python -m pydoc yourpythonfile
python -m pydoc -k ftplib
python -m pydoc -p 314
python -m pydoc -w file
I have created two sample files in a directory file1.py and file2.py which has a simple code with a single line of comment.
def f2m(ft):
""" Return the number of meters eq to feet """
return 0.30 * ft
One way to see the comment of the files is to simply write below in the same file and you can run python file.py and it would show the comments.
help(f2m)
Other way to see this is to write the command
python -m pydoc file1
One more way to see the comments in an html page by typing this command and exporting it to html
python -m pydoc -w <dir>
If you have multiple python files and if you want to generate HTML into separate folder then simple shell commands can do the job. Below code generates a folder 'htmldocs' and then generates html and moves them to this new folder. If you open any one at the right hand top corner you can see index option through which you can navigate through other pages.
mkdir -p htmldocs
pydoc -w `find . -name '*.py'`
mv *.html htmldocs