asciidoc is a pretty neat document generation and formatting system which relies on plain text files with minimum formatting codes to generate documentation in a variety of different formats. It's very easy to use and very flexible. In fact, with a bit of scripting, you can automate building an entire website using asciidoc sources. I'm aware that this method is a bit dated what with advanced database-driven CMSes to build dynamic websites these days, but it's still a neat way to create a simple, no-frills, fully portable website.

Here's a rough and ready script I wrote in Python to build a website from a directory tree. Feel free to customize it and use it as you wish.

Usage notes:

1. You need to have asciidoc and python installed on your system.
2. Save the script below as website-gen.py and make it executable (using chmod +x website-gen.py from the command line).
3. Customize the source and destination directory in the script to your needs.
4. Create the asciidoc sources in the source directory tree.
5. Create a layout.conf file (optional) or remove the -f layoutfile option from the script to use default settings.
6. Run the script to generate the output in XHTML 1.1 format in the destination directory tree.
7. For more information on asciidoc, you can read the man page and the full online documentation.

The Python script:

#!/usr/bin/env python          

import os          

# The source directory containing the asciidoc .txt files 
# (you can modify this to your needs) 
source_dir = './source/'          

# The destination directory 
# (you can modify this to your needs) 
dest_dir = './html'          

# The layout configuration file 
# (you can use your own layout file. Modify the layout file 
# to your needs or remove the 
layout_file = './layout.conf'          

# Run through the source directory and compile the asciidoc files 
for root, dirs, files in os.walk (source_dir): 
    for file in files: 
        if (file.endswith ('.txt')): 
            fullfilepath = os.path.join (root, file) 
            # Use the commented command to generate with no 
            # custom layout file 
            # command = 'asciidoc ' + fullfilepath 
            command = 'asciidoc -f ' + layout_file + ' ' + fullfilepath 
            os.system (command) 
            print fullfilepath          

print 'Completed generating documentation from sources'          

# Remove the destination directory if it exists 
command = 'rm -rf ' + dest_dir 
os.system (command)          

print 'Copying to destination dir...'          

# Copy the source dir to the destination 
command = 'cp -dpR ' + source_dir + ' ' + dest_dir 
os.system (command)          

# Remove the source files from the destination directory 
for root, dirs, files in os.walk (dest_dir): 
    for file in files: 
        if (file.endswith ('.txt')): 
            os.remove (os.path.join (root, file))          

print 'Completed successfully'