Framework/module for generating HTML documentation

Ryan Ginstrom ryang at gol.com
Tue Apr 4 04:01:43 EDT 2006


I have been maintaining a body of documentation in plain HTML files.

I would now like to automate the generation of the HTML files. Maintaining
the HTML files now is tedious and error prone, because every time I
move/remove/add a section, I have to renumber the following sections and
update my internal links.

I have looked at some of the HTML-generation frameworks, but the selection is
somewhat bewildering, and most also seem geared to generating dynamic or
static content for Websites. I guess what I am looking for is a Wiki-like
documentation generation engine, but generating a bunch of statically linked
files.

E.g., I want to go from something like this:
<h1>Introduction<h1>
<p>Some text</p>
<h1>Getting Started<h1>
<p>Some text</p>
<h2>Installation<h2>
<p>Some text. See <section>Getting Started</section> for details.</p>

To this:
[index.html]
<h1>Contents</h1>
<a href="1.html">1. Introduction</a>
<a href="1.html">2. Getting Started</a>
<blockquote>
	<a href="1.html">2.1. Installation</a>
</blockquote>

[1.html]
<h1>1. Introduction<h1>
<p>Some text</p>
<a href="index.html">Contents</a>  <a href="2.html">Next</a>

[2.html]
<h1>2. Getting Started<h1>
<p>Some text</p>
<a href="1.html">Prev</a>  <a href="index.hml">Contents</a>  <a
href="2_1.html">Next</a>

[2_1.html]
<h2>2.1. Installation<h2>
<p>Some text. See <a href="2.html">Getting Started</a> for details.</p>
<a href="2.html">Prev</a>  <a href="index.hml">Contents</a>  <a
href="2_2.html">Next</a>

If someone can recommend a framework/module that will help me achieve this, I
would greatly appreciate it. I could do it from scratch, but if this has been
tackled before (as I suspect it has), I'd like to stand on those developers'
shoulders <g>.

Regards,
Ryan

---
Ryan Ginstrom




More information about the Python-list mailing list