This page will look at tools that programmers use to document computer programs. Using comments embedded in the computer code, several publishing tools automatically produce documentation in various formats, especially .html and .pdf.

I first got interested in the topic when I learned that Project Gutenberg (PG) considers reStructured text a “tentative master format” for producing full length books. It is one of three formats (the other 2 being .html and .txt) accepted by PG to publish content.

I was surprised to learn that reStructured text comes from the Python documentation world and that got me interested in this genre of publishing.

Here is a quote from Wikipedia about documentation tools for computer programmers.

“Often, tools such as Doxygen, NDoc, Visual Expert, Javadoc, EiffelStudio, Sandcastle, ROBODoc, POD, TwinText, or Universal Report can be used to auto-generate the code documents—that is, they extract the comments and software contracts, where available, from the source code and create reference manuals in such forms as text or HTML files.”

“The idea of auto-generating documentation is attractive to programmers for various reasons. For example, because it is extracted from the source code itself (for example, through comments), the programmer can write it while referring to the code, and use the same tools used to create the source code to make the documentation. This makes it much easier to keep the documentation up-to-date.”

Contents:

  1. Introduction to reStucturedText: This document was created using .rst formatted test. It was output with Sphinx. reSt_Example
  2. This file shows the .rst file that is essentially a .txt file with special markup: reSt_Example