Python Documentation Tools
3
14
Entering edit mode
10.9 years ago
Thaman ★ 3.3k

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

tool python • 2.4k views
ADD COMMENT
0
Entering edit mode

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

ADD REPLY
0
Entering edit mode

Something i am working on

ADD REPLY
15
Entering edit mode
10.9 years ago

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

ADD COMMENT
0
Entering edit mode

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

ADD REPLY
0
Entering edit mode

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

ADD REPLY
0
Entering edit mode

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.

ADD REPLY
0
Entering edit mode

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

ADD REPLY
0
Entering edit mode

@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

ADD REPLY
0
Entering edit mode

@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

ADD REPLY
9
Entering edit mode
10.9 years ago

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.

ADD COMMENT
0
Entering edit mode
3 months ago
k • 0

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).

ADD COMMENT

Login before adding your answer.

Traffic: 1613 users visited in the last hour
Help About
FAQ
Access RSS
API
Stats

Use of this site constitutes acceptance of our User Agreement and Privacy Policy.

Powered by the version 2.3.6