Re: [docbook-apps] Website build/deploy

[Warren Young <warren@etr-usa.com>]

Dave Pawson wrote:
> 
> Some desktop icon which runs a script to build
> the entire site, stop on errors, then use
> a command line ftp command to deploy to the host.

Here's how a Unix programmer (me) does it:

I use 'make' to build the pages on my web sites from some source.  (I 
use various template languages, but it could just as well be DocBook.) 
The site copy I edit lives in a directory that the machine's local 
Apache server is set up to serve so I can reload the page in a web 
browser to check it, then I go back to the command line to say "make 
synch" which runs rsync to copy the changes in the rebuilt site up to 
the web server.

It would be trivial to set up a desktop icon to run these two non-GUI 
steps in the background: one for "make all" and the other for "make 
synch".

Here's a start at the Makefile to drive it:


DBX_SOURCES=$(shell find . -name \*.dbx -print | sort)
HTML_OUTPUTS=$(DBX_SOURCES:.dbx=.html)
HTML_SS=html-customization-layer.xsl

%.html: %.dbx $(HTML_SS)
     @xmllint --postvalid --noent --noout $<
     xsltproc $(HTML_SS) $<

html: $(DBX_SOURCES)

synch: html
     rsync -lprtvD -e ssh --delete \
             --exclude \*.dbx \
             --exclude \*.xsl \
             --exclude Makefile \
             ./ user@web.server.com:/var/www/html


The first two lines require GNU make on a Unix-like system.  It'll work 
fine on OS X, or on Windows with Cygwin installed.  They map any *.dbx 
file in the directory with the Makefile or anything underneath it to the 
corresponding name with an .html extension.  This saves you from having 
to edit the Makefile any time someone adds a page.  The cost is that the 
'make' command runs a little slower than if you'd hard-coded everything, 
but it only becomes noticeable with large sites.

The third line is for your HTML customization layer stylesheet. 
Standard DocBook stuff.

The next group of lines tells make how to create *.html from *.dbx.  If 
the .dbx file or the HTML customization layer changes, the rule tells it 
to rebuild the HTML file.  Note that we do a "lint" step before the 
build, to catch syntax errors.

Then we have the major web site building rule, the 'html' target. 
Because it's the first named target, just saying 'make' is the same as 
'make html', which builds the site's pages.

Finally, there's the 'synch' target, which ensures the 'html' target is 
up to date, then it rsyncs the deltas up to the server.  I only show 
three --exclude rules here, but in practice I find that I need lots of 
them for various reasons, which is why I break them out into one per 
line.  It makes the Makefile easier to read.

I manage several different sites with essentially this mechanism, and 
have since before the bubble popped.  For static sites, it works well.

Another advantage of using make is that a lot of GUI tools know how to 
run it, and interpret the output.  Your XML editor of choice may be able 
to do this, so you wouldn't have to build desktop icons to drive this.