Python solution for creating documentation from source files

Question

Hi, I have lots of Python (2.x) source files in a quite large project. Most of them is quite well documented - in docstrings, or comments at the beginning of classes/methods.

What I look for is a tool that would read those files and create a documentation out of it - best would be with class inheritance, method names and arguments and with the contents of those docstrings/comments extracted. Output should be a nice document that would be possible to be printed and handed together with the project as technical documentation.

I searched a bit and found a HappyDoc project, but it looks rather old and inactive.

Do you use a tool like this and are able to propose something both enough powerful to do this and still simple enough so setting it up won't take entire day?

Answer 1

Have a look at Doxygen, it is a widely used tool to generate documentation in various formats (HTML, PDF, ...) from code source and supports Python.

Answer 2

There are three tools that come to mine:

• pydoctor http://codespeak.net/~mwh/pydoctor/
• epydoc http://epydoc.sourceforge.net/
• sphinx http://sphinx.pocoo.org/

Sphinx is probably the best one to look at first, it's the one used by the core python team for the python documentation.

Answer 3

I use DoxyGen and have created an ant file that I can run from within my IDE Eclipse PyDev to generate documentation. It generates the documentation in HTML (and CHM), PDF and Word-format. I've also installed GraphViz so that the documentation is enhanced with graphical diagrams of classes and inheritance, quite nice.

DoxyGen parses the source code which is what I need. Some other document generators use introspection by running the code, but that is not what I want.

That is my 10 cent tip.

Answer 4

Sphinx in combination with the built-in autodoc and inheritance_diagram extensions should be able to do what you want. At the moment you have to name each module manually, but autodoc figures out the rest. Beware that you have to use Sphinx's syntax in all docstrings to make it work.