April 11, 2005

Versioned Reviews Implemented

The post-PyCON goal of incorporating reStructuredText processing into the Holden Web production system as a practical way of investigating how the initial architecture can be extended has now been initially achieved. A sample page is linked from this article's title.

The whole site is static HTML generated from a database. The links under "Python Reviews" in the left-hand navigation feature of the linked page are the first example of a "non-front-page" section - all previous sections in the web have navigation links to this section on both the homepage and internal pages. Eventually each section will have its own potentially unique navigation structure, though at present all internal pages use the same link structure.

The new section is generated from a new VerReview table, keyed on product name and version number. Several versions of the same project can be reviewed, and all reviews of a given project are interlinked. At the time of writing this navigation feature is demonstrated by the reviews of "wxPython"; the other reviews are single-review projects. Only one review of any project appears in the navigation bar (currently the most recent).

The main new feature used to produce the reviews is this ability to generate web page images in two steps -- each row in the VerReview table claims its own row in the Pages table, and a separate module handles the generation of the Page rows (each of which is a page in the finished site) from the VerReview rows. So some of the content is now generated from a separate table, potentially with its own relationships. This architecture could relatively easily define a plug-in API for new tables and publishing components, although it does not yet do so.

Once the section's content has updated the site's main Pages table the normal content interlinking processes handle the integration of this new content in just the same way as always. [The existing design will not gracefully handle sections with a large number of items, but the potential is clear and aspects of the data like recency could be used to reduce section size where necessary].

A further first is the use of reStructuredText, the format developed by the docutils project, to generate web content. Note that reStructuredText-for-the-web does not exploit many of the web's more versatile (and sometimes therefore more dangerous) possibilities, in the interests of maintaining a uniform concept of "document" across as many media as possible.

It would be imprudent to treat this as anything but a database publishing demonstration. The limited hypertext that the docutils software does handle proved very useful in generating the inter-version links between the different reviews of a project, but this capability should no tbe pushed too far. Further iterations can, if deemed desirable, generate reStructuredText in tables similar to VerReview from yet further content in as-yet-unknown tables.

Holden Web is grateful to David Goodger for guidance in navigating the distutils architecture to arrive at a first attempt production system that uses no external processes. Thanks also to Dave Beaudoin of Samara Design and Tim Parkin of Pollenation Internet for assistance with look-and-feel abd graphical design. The production system originates with Holden Web.

April 8, 2005

docutils Install Review

This is the entire review for a docutils install I recently performed:

Very simple installation under Cygwin: literally unpack the tar file, change to the source directory and run

python setup.py install

No errors, docutils is now a site-package!
Now that PyCon is over I've had a little time to start tweaking a feature I've wanted to add to the Holden Web site for quite a while. I end up looking at, and frequently installing, a lot of open source software. The installation routines are of variable quality and sometimes I have to stumble my way through, sometimes I never get to the end.

So the new "Python Reviews" section (which may end up being renamed) is there to report on installation activity. It is also a test bed for my first significant use of reStructuredText (of which more later), so I suppose it's appropriate that this blog's title links to the install review for the docutils software that converts reStructuredText into HTML.

As with other non-production features the section isn't listed on the home page, but it should appear in the left-hand navigation bar of all body pages. The article format is still experimental, and decisions about whether it's worth keeping the source in a database rather than in files remain to be addressed.

The news feature is currently driven by analysing the results of a search for "Python" in O'Reilly's meerkat feed, but it isn't yet updating automagically on the new host, and other sources should ideally be included.