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!