Differences between revisions 19 and 22 (spanning 3 versions)
Revision 19 as of 2010-05-02 11:40:55
Size: 3992
Editor: techtonik
Comment: docutils is not API generator, adding Sphinx also
Revision 22 as of 2010-05-02 12:21:04
Size: 4093
Editor: techtonik
Comment: removing Teud and Crystal - no more available
Deletions are marked like this. Additions are marked like this.
Line 24: Line 24:
 * HappyDoc, http://happydoc.sourceforge.net/
Line 27: Line 26:
 * [[Crystal]] - produces output that is similar to Wiki:JavaDoc.
Line 29: Line 27:
 * [[Teud]], EfnetPythonWiki:TeudProject
Line 31: Line 28:
 * Pudge, http://pudge.lesscode.org/
 * Endo, part of the Enthought Tool Suite (http://code.enthought.com/ets/), is aware of Traits-based attributes (Traits is also part of ETS); uses ReStructuredText or plain text in docstrings and in plain comments that immediately precede variable assignments; and generates HTML output.
 * [[https://svn.enthought.com/enthought/wiki/EndoHowTo|Endo]] from Enthought Tool Suite - generates HTML API documentation from docstrings and from plain comments that immediately precede variable assignments.
Line 34: Line 30:

 * [[http://happydoc.sourceforge.net/|HappyDoc]] ([[http://sourceforge.net/projects/happydoc/forums/forum/30132/topic/3563472?message=8100340|not supported]]) - documentation extraction tool that uses the parse tree for a module to derive the information used in its output, rather that importing the module directly.
 * [[http://pudge.lesscode.org/|Pudge]] (defunct)

Python modules are usually documented using docstrings. You can read a module's docstrings from the Python interactive prompt with the help() function. For example:

import distutils
help(distutils)

The help() function uses Python's standard pydoc module, as does the pydoc command that comes with Python.

The various documentation tools available generally do one of two things:

  • they either process docstrings in some way to make finding/reading documentation on a given module easier (so-called "API documentation tools"), or
  • they have nothing to do with docstrings and instead focus on processing documentation in some way (such as converting your plain text docs into html)

Currently, the Python docs consist of 2 parts:

  • the API docs that you can read using the help() command (pydoc can also provide these as html and even serve them from your local machine), and

  • the manuals/guides/howtos at http://python.org/doc/ which are written in reStructuredText (a plain text format) and processed into various output formats by the Sphinx tool.

When writing documentation for your own modules (either as manuals or docstrings (preferably both)), I suggest you use a plain text markup such as reST or Markdown.

Automatic Python API documentation generation tools

Documentation processing tools

Other projects that can be used to produce API documentation

  • XIST - an XML based extensible HTML generator written in Python.

  • HtmlGen - a Python library for generating HTML documents.

Other documentation processing tools

  • Pandoc -- written in Haskell, this tool can read and write a number of formats (including reST).


CategoryDocumentation

DocumentationTools (last edited 2023-02-04 13:42:35 by GilOliveira)

Unable to edit the page? See the FrontPage for instructions.