Making This Website

How I made this easy for myself

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.

Note:

Every tool on this page comes installed by default on
Macintosh OS X 10.4 with the exception of the docutils package
that provides rst2html.py. Here is how you get and install that package
from the terminal:

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

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.

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.

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:

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:

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.

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:

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:

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:

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.