Differences between revisions 2 and 31 (spanning 29 versions)
Revision 2 as of 2003-10-06 21:31:44
Size: 1115
Editor: MikeRovner
Comment:
Revision 31 as of 2013-08-28 17:36:52
Size: 4681
Comment: apydia is inactive
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
Automatic Python API documentation generation tools:
 * DocUtils, http://docutils.sourceforge.net/ ReStructuredText processing engine
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 [[http://daringfireball.net/projects/markdown/|Markdown]].

== Automatic Python API documentation generation tools ==

 * autosummary, an extension for the Sphinx documentation tool: http://sphinx.pocoo.org/ext/autosummary.html
 * [[http://sphinx.pocoo.org/ext/autodoc.html|autodoc]], a Sphinx-based processor that processes/allows reST doc strings,
 * PyDoc, http://pydoc.org/ documentation browser (in HTML) and/or an off-line reference manual. Also in the standard library as [[http://docs.python.org/lib/module-pydoc.html|pydoc]]
 * pydoctor, http://codespeak.net/~mwh/pydoctor/ replacement for now inactive Epydoc, pydoctor was born for the needs of Twisted project
 * Doxygen < http://www.doxygen.org > can create documentation in various formats (HTML, LaTeX, PDF, ...) and you can include formulas in your documentation (great for technical/mathematical software). Together with Graphviz < http://www.research.att.com/sw/tools/graphviz/ > it can create diagrams of your code (inhertance diagram, call graph, ...). Another benefit is that it handles not only Python, but also several other programming languages like C, C++, Java, etc.

= No longer under development =

 * Another PythonDoc - uses JavaDoc-style comments, and produces HTML and XML output. Can also be used as a library, producing ElementTree descriptions of your source code. http://effbot.org/zone/pythondoc.htm
Line 4: Line 32:
 * HappyDoc, http://happydoc.sourceforge.net/
 * PyDoc, http://web.pydoc.org/
 * PythonDoc - uses ReStructuredText input format, and can produce HTML and XML output. It uses XML as an intermediate representation, to simplify the addition of new output formats. http://starship.python.net/crew/danilo/pythondoc/
 * ["Crystal"] - produces output that is similar to JavaDoc.
 * EasyDoc - uses an HTML-like markup language, similar to the language used by JavaDoc; and produces HTML output (http://htmltmpl.sourceforge.net/easydoc.html)
 * ["Teud"], http://twistedmatrix.com/users/jh.twistd/python/moin.cgi/TeudProject
 * [[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.
 * [[http://pudge.lesscode.org/|Pudge]] (defunct)
 * [[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.
 * EasyDoc - uses an HTML-like markup language, similar to the language used by Wiki:JavaDoc; and produces HTML output (http://htmltmpl.sourceforge.net/easydoc.html)
 * PythonDoc - uses StructuredText input format (''not'' reST), and can produce HTML and XML output. It uses XML as an intermediate representation, to simplify the addition of new output formats. http://starship.python.net/crew/danilo/pythondoc/
 * Apydia, http://apydia.ematia.de/
Line 11: Line 39:
Other projects that can be used to produce API documentation:
 * [http://www.livinglogic.de/Python/xist/index.html XIST] - an XML based extensible HTML generator written in Python.
 * [http://starship.python.net/crew/friedrich/HTMLgen/html/main.html HtmlGen] - a Python library for generating HTML documents.
== Documentation processing tools ==

 * DocUtils, http://docutils.sourceforge.net/ [[reStructuredText]] processing engine
 * [[Sphinx]], http://sphinx.pocoo.org/ - converts reStructuredText documentation into various formats

== Other projects that can be used to produce API documentation ==

 * [[http://www.livinglogic.de/Python/xist/index.html|XIST]] - an XML based extensible HTML generator written in Python.
 * [[http://starship.python.net/crew/friedrich/HTMLgen/html/main.html|HtmlGen]] - a Python library for generating HTML documents.

== Other documentation processing tools ==

 * [[http://johnmacfarlane.net/pandoc/|Pandoc]] -- written in Haskell, this tool can read and write a number of formats (including reST).
 * [[http://www.unexpected-vortices.com/sw/gouda/|Gouda]] -- a Python script (which uses Pandoc under the hood) to generate multi-chapter html documents from Markdown text files.

----
CategoryDocumentation

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

  • autosummary, an extension for the Sphinx documentation tool: http://sphinx.pocoo.org/ext/autosummary.html

  • autodoc, a Sphinx-based processor that processes/allows reST doc strings,

  • PyDoc, http://pydoc.org/ documentation browser (in HTML) and/or an off-line reference manual. Also in the standard library as pydoc

  • pydoctor, http://codespeak.net/~mwh/pydoctor/ replacement for now inactive Epydoc, pydoctor was born for the needs of Twisted project

  • Doxygen < http://www.doxygen.org > can create documentation in various formats (HTML, LaTeX, PDF, ...) and you can include formulas in your documentation (great for technical/mathematical software). Together with Graphviz < http://www.research.att.com/sw/tools/graphviz/ > it can create diagrams of your code (inhertance diagram, call graph, ...). Another benefit is that it handles not only Python, but also several other programming languages like C, C++, Java, etc.

No longer under development

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

  • Gouda -- a Python script (which uses Pandoc under the hood) to generate multi-chapter html documents from Markdown text files.


CategoryDocumentation

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

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