Python Documentation Tools

Question

[Thaman]

What are the tools available to bring out the Documentation of Python developed applications? I search in the internet but couldn't find out any reliable one mostly focus on python. Wanted to know how you guys do your technical documentation.

Thanks in advance

[David W]

Hi Thaman, do you mean writing docs for something you're working on or reading docs for something your using?

[Thaman]

Something i am working on

Answer 1

[Brad Chapman]

For writing documentation, try Sphinx, which is used for the main Python documentation:

http://sphinx.pocoo.org/

For generating automated API docs from source code, pydoc is included with Python:

http://docs.python.org/library/pydoc.html

[brentp]

+1 for sphinx, it's pretty easy to go from restructured text and get some nice looking docs with various sphinx themes.

[Thaman]

Sphinx seems to be a great tool but still struggling to bring out my documentation.

[Thaman]

Sphinx seems to be a great tool but i am wondering whether it will be appropriate for my project documentation because it's python cgi and most the lines of code came to be HTML.

[Markf]

Sphinx certainly generates nice looking output, a somewhat more lightweight solution (IMHO) for generating documentation is epydoc.

[Ryan Dale]

@Thaman: you can set the highlight language (anything that Pygments supports) on a per-codeblock basis. Or you can set the global default to be HTML with the highlight_language variable in conf.py

[Ryan Dale]

@Brad Chapman, @MarkF: It's true that pydoc and epydoc may be more lightweight solutions for auto-generated docs. But if you go with Sphinx, you get that auto-functionality in addition to all the rest of Sphinx: http://sphinx.pocoo.org/tutorial.html#autodoc

Answer 2

[Giovanni M Dall'Olio]

A nice library for writing documentation is doctest. It enables you to write examples of how your code should be executed in your documentation, for example:

def factorial(n):
    """Return the factorial of n, an exact integer >= 0.

    If the result is small enough to fit in an int, return an int.
    Else return a long.

    >>> [factorial(n) for n in range(6)]
    [1, 1, 2, 6, 24, 120]
    >>> [factorial(long(n)) for n in range(6)]
    [1, 1, 2, 6, 24, 120]

The nice part is that you can run the examples in the documentation as if they were real code, and see if they return the same result. It is a great way to keep the documentation consistent with the code, because if you write an example that doesn't work, you will get an error.

Answer 3

[k]

One option is Pdoc which, similarly to builtin Pydoc, extracts Python docstring documentation automatically. But, compared to the latter, it produces somewhat more nicely formatted and navigable output (example).