Differences between revisions 12 and 16 (spanning 4 versions)
Revision 12 as of 2006-06-05 15:19:37
Size: 2595
Editor: 66
Comment: updated pydoc links
Revision 16 as of 2009-09-20 21:58:20
Size: 3860
Editor: ool-4356421f
Comment: Added some overview content at the top. Created some sections below.
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
Automatic Python API documentation generation tools: Documentation of Python modules is most-often done by adding docstrings to your code. You can read a module's docstrings from the Python interactive prompt (the "REPL") by using 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.
Line 3: Line 8:
---- /!\ '''Edit conflict - other version:''' ----
 * 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]
The various documentation tools available generally do one of two things:
Line 6: Line 10:
---- /!\ '''Edit conflict - your version:''' ----
 * 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]
 * 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)
Line 9: Line 13:
---- /!\ '''End of edit conflict''' ---- 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 ==

 * 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]]
Line 15: Line 28:
 * ["Crystal"] - produces output that is similar to Wiki:JavaDoc.  * [[Crystal]] - produces output that is similar to Wiki:JavaDoc.
Line 17: Line 30:
 * ["Teud"], EfnetPythonWiki:TeudProject  * [[Teud]], EfnetPythonWiki:TeudProject
Line 21: Line 34:
 * Apydia, http://apydia.ematia.de/
Line 22: Line 36:
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 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).

Documentation of Python modules is most-often done by adding docstrings to your code. You can read a module's docstrings from the Python interactive prompt (the "REPL") by using 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

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

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

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