Other Documentation Tools

<h3>Other Documentation Tools</h3>

<p>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.</p>

<p>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!</p>

<h3>Source-embedded Documentation</h3>

<ul>
<li> <a href="http://java.sun.com/j2se/javadoc/">JavaDoc</a> -- Perhaps the most widely
accepted embedded-source documentation. <p /> </li>
<li> <a href="http://sirtaj.net/projects/kdoc/">kdoc</a> --
Yet another implementation of JavaDoc for C++ and IDL; this one is used for the <a href="http://www.kde.org/">KDE project</a>. <p /> </li>
<li> <a href="http://www.tecgraf.puc-rio.br/~tomas/luadoc/"
>LuaDoc</a> -- Variation of JavaDoc used with the <a href="http://www.tecgraf.puc-rio.br/lua/">Lua</a> embeddable

System Message: WARNING/2 (<string>, line 27)

Block quote ends without a blank line; unexpected unindent.

scripting language. <p /> </li>

<li> <a href=
"http://www.perl.com/pub/doc/manual/html/pod/perlpod.html" >POD ("Plain Old Documentation")</a> -- that Perl thing. This

System Message: WARNING/2 (<string>, line 33)

Block quote ends without a blank line; unexpected unindent.
can be used either embedded in Perl source or in separate <font
face="sans-serif">.pod</font> files placed alongside the

System Message: WARNING/2 (<string>, line 35)

Definition list ends without a blank line; unexpected unindent.

modules being documented. Conversion tools are available which convert to plain text, HTML, LaTeX, and others. <ul>

System Message: ERROR/3 (<string>, line 38)

Unexpected indentation.
<li> <a href=
"http://world.std.com/~swmcd/steven/perl/module_pod.html" >How to write POD for a module</a></li>
<li> <a href=
"http://world.std.com/~swmcd/steven/perl/program_pod.html" >How to write POD for a program/script</a></li>

System Message: WARNING/2 (<string>, line 44)

Block quote ends without a blank line; unexpected unindent.

</ul> <p /> </li>

<li> <a href="http://synopsis.sourceforge.net/">Synopsis</a> --
Cross-language documentation generator, currently supports IDL and C++. Written mostly in Python (download from the <a href="http://sourceforge.net/projects/synopsis/">SourceForge project page</a>). <p /> </li>
<li> <a href=
"http://www.oche.de/~akupries/soft/autodoc/">AutoDoc</a> --

System Message: WARNING/2 (<string>, line 56)

Block quote ends without a blank line; unexpected unindent.

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. <p /> </li>

<li> <a href="http://www.xs4all.nl/~rfsber/Robo/robodoc.html"
title="ROBODoc">ROBODoc</a> -- Another multi-lingual tool,

System Message: WARNING/2 (<string>, line 63)

Block quote ends without a blank line; unexpected unindent.

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). <p /> </li>

<li> <a href="http://SmallEiffel.loria.fr/man/short.html">short</a>
-- Documentation extraction tool distributed with <a
href="http://SmallEiffel.loria.fr/">GNU SmallTalk</a>; looks

System Message: WARNING/2 (<string>, line 73)

Definition list ends without a blank line; unexpected unindent.

like it's more of a modified pretty-printer than a text documentation tool. <p /> </li>

<li> <a href=
"http://www.helpmaster.com/help/devaids/popautoduck.htm" >AutoDuck</a> -- Tool for extracting embedded documentation

System Message: WARNING/2 (<string>, line 80)

Block quote ends without a blank line; unexpected unindent.

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. <p /> </li>

<li> <a href="http://www.stack.nl/~dimitri/doxygen/">Doxygen</a> --
Embedded documentation tool for C and C++. It provides <a
href="http://www.stack.nl/~dimitri/doxygen/commands.html" >special commands</a> that can be embedded in marked comments

System Message: WARNING/2 (<string>, line 89)

Definition list ends without a blank line; unexpected unindent.

that look quite TeXish, and supports some JavaDoc-style marks as well. This is a derivative of DOC++. <p /> </li>

<li> <a href="http://www.zib.de/Visual/software/doc++/">DOC++</a> --
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.) <p /> </li>
<li> <a href="http://www.tall-tree.com/">DocJet</a>

(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. <p> Examples of marked source are hard to dig out on the Web site, but there are examples for:</p> <ul>

System Message: ERROR/3 (<string>, line 109)

Unexpected indentation.
<li> <a href=
"http://www.tall-tree.com/docjet/samples/VBAddIn/GenPipe_CPP.html" >C++</a>
<li> <a href=
"http://www.tall-tree.com/docjet/samples/VBAddIn/Connect_CLS.html" >Visual Basic</a>

System Message: WARNING/2 (<string>, line 115)

Block quote ends without a blank line; unexpected unindent.

</ul> <p /> </li>

<li> <a href="http://www.doc-o-matic.com/">Doc-O-Matic</a>
(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. <a href="http://www.doc-o-matic.com/examplesourcecode.html">An example</a> of embedded documentation is available on the website, as is the <a href="http://www.doc-o-matic.com/help.html">Doc-O-Matic manual</a>. </li>

System Message: WARNING/2 (<string>, line 130)

Definition list ends without a blank line; unexpected unindent.

</ul>

<h3>Out-of-line Documentation</h3>

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

<ul>
<li> <a href="http://www.seanet.com/~hgg9140/comp/index.html" >PDX
("POD Extended")</a> is an extended form of Perl's POD markup language. The translator implementation is written in Python. </li>

System Message: WARNING/2 (<string>, line 144)

Definition list ends without a blank line; unexpected unindent.

</ul>

<h3>Literate Programming Systems</h3>

<p>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:</p>

<ul>
<li> <a href="http://www.faqs.org/faqs/literate-programming-faq/"
title="The Literate Programming FAQ">The Literate Programming FAQ</a>

System Message: WARNING/2 (<string>, line 157)

Block quote ends without a blank line; unexpected unindent.

</li>

<li> <a href="http://www.desy.de/user/projects/LitProg.html"
title="The Literate Programming Library">The Literate Programming Library</a>

System Message: WARNING/2 (<string>, line 161)

Block quote ends without a blank line; unexpected unindent.

</li>

<li> <a href="http://www.webring.org/cgi-bin/webring?ring=litprog;list"
title="The Literate Programming Web Ring (list)">The Literate Programming Web Ring (list)</a>

System Message: WARNING/2 (<string>, line 165)

Block quote ends without a blank line; unexpected unindent.

</li>

System Message: WARNING/2 (<string>, line 166)

Definition list ends without a blank line; unexpected unindent.

</ul>

<p>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 <a

System Message: ERROR/3 (<string>, line 171)

Unexpected indentation.
href="mailto:fdrake@acm.org" title="e-mail Fred!">let me know</a>!

System Message: WARNING/2 (<string>, line 172)

Block quote ends without a blank line; unexpected unindent.

</p>

Notice: While Javascript is not essential for this website, your interaction with the content will be limited. Please turn Javascript on for the full experience.