Documentation is a very important but often neglected feature of programming. In the C/C++ world doxygen is often used whereas in the Java world javadoc comments are important. More or less by accident I found the documentation tool for python sources: pydoc.
The principle of standard doc tools is very simple: Write your source code, comment it with special tags and run a program over it which generates HTML sites. These sites can now be viewed with an Browser of your choice.
And now comes python! Like javadoc in the Java distribution, pydoc is shipped with the python sources. Here is the output from the help command:
bash:~$ pydoc -h pydoc - the Python documentation tool pydoc... Show text documentation on something. may be the name of a Python keyword, topic, function, module, or package, or a dotted reference to a class or function within a module or module in a package. If contains a '/', it is used as the path to a Python source file to document. If name is 'keywords', 'topics', or 'modules', a listing of these things is displayed. pydoc -k Search for a keyword in the synopsis lines of all available modules. pydoc -p Start an HTTP server on the given port on the local machine. pydoc -g Pop up a graphical interface for finding and serving documentation. 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.
Please notice that a small documentation server can be started with pydoc -p 6767 or pydoc -g! This is everything your need.
So do the following:
As you can see now, your written sources are included and package dependencies are resolved, too!
If your're satisfied with your documentation, you can now export the sites with pydoc -w ..