What is it?

buildhtml2.py is used to generate my website from reStructuredText (reST) source. The generated website consists of mostly static XHTML pages, with a few plain text files and software tarballs thrown in for good measure.

The generated website has a fairly standard heirarchical file structure. There is a single header and footer applied to every generated page, and every page links to the same CSS style file. This provides a consistent look throughout the site. The header contains a logo, search bar, and navigation bar. The footer contains a copyright notice, links for validating the current page, and a mention at the bottom that the page was generated from reST source.

Advantages

Here are some advantages of using reST markup as the source content of a website:

• well-documented, well-designed, extensible, mature, lightweight markup language. Wiki markup just can't touch reST.
• Use the same source documents for generating printed documentation. reST can generate LaTeX now, which can provide beautiful PDFs. It can also generate XML which is easily transformed into other markups. But unlike writing documents directly in XML with, say, docbook, reST is very readable as plain text.
• use the same markup for README files, full-blown documentation, and web pages. reST is unmatched in being able to "go anywhere." People who download your software can read a README file as plain text without having any special tools installed. And putting the same README on a nicely formatted webpage can be fully automated.

Are there any disadvantages to reST? Its biggest drawback is that it isn't too widely used yet. But that is changing, and some wikis and blogging tools are supporting it now.

Because of the reST header and footer directives, almost no HTML needs to be maintained directly. In fact, presently the search form is the only piece of human-edited HTML on my entire website. That's about 7 lines of HTML. This is a testament to the power of reST for doing logical markup, and CSS for doing visual layout and formatting.

For an example of reST in action, check out the source for this page. You can also try the link at the very bottom of every web page on this site to view its reST source and get a feel for it.

Download

• buildhtml2.tgz

License

The main file is GNU GPL, but each file in the distribution have its own copyright notice. I'm looking into Creative Commons licenses to see what I like best and may update this in the future.