by Brandon Rhodes • Home

Sphinx + Mercurial = My favorite CMS

Though I write and maintain some of the content for our Python Atlanta web site, updates and additional content often come in from other users. For example, our Plone interest group — headed up by Christopher Johnson — has their own page on our web site. And the information about our book club is both written and regularly updated by Doug Hellmann.

How can a collaborative site like ours best be edited and updated? Well, I would like to report some modest initial success with an experimental approach: I now maintain the site as a Sphinx-powered documentation system stored in a BitBucket repository into which I pull changes made by my collaborators. The advantages are several.

• The change management tools supported by traditional CMS systems, even at their best, seem somehow anemic when compared to the toolkit provided by a good DVCS like Mercurial. Where, for example, does even a capable CMS like Plone provide anything like Mercurial's “backout” or “blame” commands?
• Markup as well-designed as reStructuredText is not only a lot of fun to use, bit it also very cleanly separates content from design. Authors working in plain text tend to produce clean, readable content without the messy markup often associated with visual HTML editors, or, worse yet, the disaster that is Microsoft Word.
• Staging — a feature I find essential, but which seems missing from many default CMS configurations — occurs automatically! Each author can see locally how the site will look with their changes, and after doing a pull I can review the site's appearance on my laptop before finally deploying the new content to the production site.

To top it all off, authors get to use their own editor-of-choice when making contributions, and we all get extra practice cloning and merging in my favorite DVCS. I am optimistic about this direction, but I will post again if we wind up hitting snags in the future. Finally, of course, feel free to clone our repository if you want to see how Sphinx looks when running a generic web site.

©2021