Other Documentation Tools
Other Documentation Tools
When considering the state of documentation tools for Python, one should consider what is being done for other systems. This should include tools that work with documentation embedded in source code and tools that work with separated documentation.
If you can think of additional tools that should be noted, please let me know about them (free or commercial). If you can point to an example of the markup, that would be great; thanks!
Source-embedded Documentation
- JavaDoc -- Perhaps the most widely
accepted embedded-source documentation.
- kdoc --
Yet another implementation of JavaDoc for C++ and IDL; this one
is used for the KDE project.
- LuaDoc -- Variation of JavaDoc used with the Lua embeddable
scripting language.
- POD ("Plain Old Documentation") -- that Perl thing. This
can be used either embedded in Perl source or in separate .pod files placed alongside the
modules being documented. Conversion tools are available which
convert to plain text, HTML, LaTeX, and others.
- Synopsis --
Cross-language documentation generator, currently supports IDL
and C++. Written mostly in Python (download from the SourceForge
project page).
- AutoDoc --
Documentation generator for Tcl. I don't see any online
examples of actual source files, but the sources for the tool
are documented using itself.
- ROBODoc -- Another multi-lingual tool,
supports C, C++, Java, Assembler, Basic, Fortran, LaTeX,
Postscript, Tcl/Tk, LISP, Forth, Perl, Shell Scripts, Occam,
COBOL, HTML, and others (according to their blurb). I don't
see any links to examples that aren't part of their
documentation (hence, heavily marked and annotated).
- short
-- Documentation extraction tool distributed with GNU SmallTalk; looks
like it's more of a modified pretty-printer than a text
documentation tool.
- AutoDuck -- Tool for extracting embedded documentation
from C, C++, Assembly, and BASIC. Output formats include HTML
and RTF (for generating WinHelp files).
This tool was written by Eric Artzt, a Microsoft employee.
- Doxygen --
Embedded documentation tool for C and C++. It provides special commands that can be embedded in marked comments
that look quite TeXish, and supports some JavaDoc-style marks
as well. This is a derivative of DOC++.
- DOC++ --
Documentation system for C, C++, and Java; the inputs are C/C++
header files with markup or Java source files. It can output
HTML and LaTeX. (No real examples of input sources online.)
- DocJet
(commercial)
Documentation tool for C, C++, Java, MS IDL, and Visual Basic.
The comments look pretty reasonable; it looks like a good bit
of effort goes into identifying identifiers in the comment text
and turning them into hyperlinks.
Examples of marked source are hard to dig out on the Web site, but there are examples for:
- Doc-O-Matic (commercial) Documentation tool for C++ and Object Pascal/Delphi. This tool supports source-embedded API documentation, external API documentation, and online help and general application manuals. An example of embedded documentation is available on the website, as is the Doc-O-Matic manual.
Out-of-line Documentation
Please send me a note if you can think of anything that really needs to be listed here. Remember, we're interested in markup targeted specifically at reference documentation for programming APIs (in any language).
- PDX ("POD Extended") is an extended form of Perl's POD markup language. The translator implementation is written in Python.
Literate Programming Systems
Literate programming systems are also available, but are not covered in this list. I think it would be fair to describe these as "Document-embedded Source." Further information can be found at:
- The Literate Programming FAQ
- The Literate Programming Library
- The Literate Programming Web Ring (list)
These resources don't appear to have been updated recently, and I know there are newer systems that have become available. If you have information about an up-to-date reference resource, please let me know!