Introduction

I'd like to share how I build this website because I have a pretty easy system that produces decent results. Best of all, I don't write a single line of HTML! This document explains end-to-end how I write pages, convert them to HTML, apply stylesheets and upload to my web hosting provider.

I researched existing web creation systems and found 99% of them to be overkill for my needs. All I want to do is make simple static pages with a few images here and there. I want to add links where appropriate. I want an edit-and-go solution. I don't want to have to consult a how-to every time I make a new page and I don't want a character-excessive wiki format.

$ curl -# ftp://ftp.berlios.de/pub/docutils/docutils-snapshot.tgz | tar -zxvf -
$ cd docutils
$ python setup.py install

ReStructured Text

As a Python programmer, I've been aware of reStructured Text (ReST) and known it to be a good lightweight markup syntax capable of producing HTML and LaTex output. I've used ReST and the rst2html.py tool to make individual pages for a couple of years, but never in a comprehensive system as I am detailing in this document.

First let me show you how easy and clean ReST is in its raw form. Here are the top few lines of the source text file that created this page:

===================
Making This Website
===================
How I made it easy on myself
============================

:Copyright: Copyright 2007 Dean Hall. All rights reserved.
:Author: Dean Hall
:Date: 2007/07/31

Introduction
------------

I'd like to share how I build this website because I have a pretty
easy system that produces decent results.

Pretty nice, huh? The raw text has elements that make the text visually appealing and obvious in intent. Creating a link is pretty easy, you do it like this:

`Creating a link`_ is pretty easy, you do it like this:

.. _`Creating a link`: pagedoesnotexist.html

And lastly, adding an image (no image shown here; just the source):

.. image:: someImage.jpg
   :width: 240
   :alt: Text explaining the image
   :align: right
   :target: someImage.jpg

Using the :width: argument means that your web browser will size someImage.jpg to be 240 pixels wide even though it may be bigger or smaller than that. This is an easy way to avoid having to create a thumbnail image. I then use the :target: argument so you can click on the image and get the full-size image on a page by itself.

Using rst2html.py

Once the source ReST file is created, a command line tool is used to convert it to the desired output format. In this case I want HTML, so I use the script rst2html.py to create the output file. The simplest use of rst2html.py is as follows:

rst2html.py ThisWebsite.txt > ThisWebsite.html

In the above case, the script generates an HTML file and embeds a default set of CSS elements. This results in a bland black and white page. Easy, basic and quick.

Latex Equations

I wrote a page on the Kalman Filter that necessitated the ability to embed good-looking equations into the html. I found that John Gill wrote an experimental directive to generate a PNG file from LaTeX equations in ASCII format and link the PNG into the resulting HTML file. Here's how to use the directive (or role) in the source:

:latex:`$x_{k} = A * x_{k-1} + B * u_{k-1} + w_{k-1}$`

And the output it generates:

The down side is that the output has non-html at the top that needs to be removed by hand.

Cascading Style Sheets (CSS)

I prefer my pages to have a modicum of color and style, so I created a CSS file to augment the default output. My CSS file looks like this:

@import url(html4css1.css);

body {
    background-color: black;
    margin-left: 5%;
    margin-right: 5%;
}

h1 {
    color: #ffffff;
    background-color: #551a8b;
    font-family:  Arial, Helvetica;
    margin-bottom: 0px;
    padding-left: 16px;
}

h2 {
    color: #ffffff;
    background-color: #551a8b;
    font-family:  Arial, Helvetica;
    margin-bottom: 0px;
    padding-left: 32px;
}

p, li, table {
    padding-left: 16px
}

.section {
    color: #000000;
    background-color: #ffffff;
    padding-bottom: 5px;
}

The import statement includes ReST's default CSS file, html4css1.css. The elements I use create the black page background, white section background and purple section header backgrounds. That's just a look I chose.

I can change the look just by changing the CSS file. I want to be able to change the look without having to recompile my ReST files, so in the command line, I have rst2html.py link to the stylesheet rather than embed it:

rst2html.py --stylesheet=dwh-docutils.css --link-stylesheet ThisWebsite.txt > ThisWebsite.html

Using a Makefile for Building the Site

Of course, I can't remember the proper command line switches from one week to the next, so I use a Makefile system to build my entire website. This way, I only have to configure my command lines once, and just type make to build it all. It's that easy.

A Makefile is just a way to tell the make tool how to run a command line tool to generate desired target files. Here are the pertinent contents of my Makefile that run the rst2html.py tool:

textfiles = $(wildcard *.txt)
htmlfiles := $(patsubst %.txt,%.html,$(textfiles))
CSSFILE := dwh-docutils.css
SUBDIRS = ApuLcd Etching Mmb103 PastRobots UsbProgSharp Argonaut

.PHONY: all clean cleansubdirs subdirs $(SUBDIRS)

all: html subdirs

subdirs: $(SUBDIRS)

$(SUBDIRS):
    $(MAKE) -C $@

$(htmlfiles): %.html: %.txt
    rst2html.py --stylesheet=$(CSSFILE) --link-stylesheet $< > $@

html: $(SUBDIRS) $(htmlfiles)

clean:
    $(RM) $(htmlfiles)

All the stuff about subdirs is how I build all the subdirectories of my website. The clean target is supposed to delete the HTML files; I don't use it much. I put a copy of this Makefile (with small changes) in every directory so I can tailor which subdirectories get built and become a part of my website.

Colorizing Python Source Code

I write Python scripts quite a bit and I like to share them. However, if I just put a Python script in my website's filesystem, my web host provider's web server configuration assumes it should execute that file instead of displaying it.

I override the general web server configuration by creating a .htaccess file in whichever directory I need to configure. So I created a rule that runs a colorization script whenever a URL ends in .py. Here is the contents of the .htaccess file that performs this:

AddHandler application/x-python .py
Action application/x-python /bin/colorize.cgi

I then put the colorize.cgi file at ~/mywebsitedir/bin/colorize.cgi.

This means that the colorizer script runs every time someone accesses one of my Python scripts, but this was the easiest solution I could find. Here is an example.

Hiding Sensitive PDF Files

I operate a few technical projects where I want to share a great deal of the information about the project, but not everything. For example, I want to give all sorts of details about my robot project, Argonaut; however, I don't want the world to see the purchase receipts that I save as PDF files.

Again, I use a .htaccess file to prevent outsiders from viewing these files:

<Files *.pdf>
order allow,deny
deny from all
</Files>

Uploading Using rsync

There is also an install target in the Makefile that I didn't show previously. It's only in the root Makefile and it is responsible for installing (copying) my local website to the filesystem at my web hosting provider. Here is the install target, it's pretty simple:

install: html
    rsync -urvz -e ssh . dwhall@tejava.dreamhost.com:/home/dwhall/deanandara.com

As you can see, it uses rsync to copy, recursively, only the files that have changed (and compress them for transmission). I use the ssh conduit for security and because I've set up a crypto system that means I don't have to type my password every time.

Making Changes

With all of the above in place, my website editing process goes like this:

1. Edit an existing .txt file or create a new one in ReST format.
2. Type make to build the HTML locally. If it looks good then...
3. Type make install to copy new or changed files to my website.