code warehouse

Soho tutorial

Table of contents

You want to build your next web site. You have decided that you want a static site. You want to write the content in reStructuredText and the layout in TAL. You may want Soho. You want to use Soho. Resistance is futile.

This short tutorial will explain the steps taken to build a site very similar to this very web site. Note that the tutorial covers all features of Soho, though some of them are better covered in other documents. Enough talking, let's write this web site.


This tutorial is under progress. If you happen to be interested, feel free to bug me until I complete it...


First, create a new directory. This will be your working directory, which you may want to put in the versioning system of your choice (e.g. Subversion or CVS):

$ mkdir
$ cd

We then would like to put our content in a src directory:

$ mkdir src
$ cd src

We are ready to go. We will see later that directory may contain other files but, for now, we do not need any of them.


Soho looks at reStructuredText files (.txt or .rst). Let's create the index page of our site, index.txt:

Welcome to

Welcome to this test web site.

.. image:: gnu.jpg
   :width: 129
   :height: 122
   :alt: A gnu

You may also want to look at the `installation page`_.

.. _installation page: install.html

For the sake of the example, we will download this image of a gnu and rename it gnu.jpg in the src/ directory.

We will also create another source file named install.txt:


To **install** Foo, simply double-click on the *blob*.

Now that we have our content, we can go on with the layout.


The layout is represented by a Zope Page Template file, which we will name and put it in directory. We will begin with this very simple template (which does not conform to HTML or XHTML, but we will not care about that, for now):

<metal:block define-macro="master">
  <h1 tal:content="context/meta/title"></h1>
  <tal:content tal:replace="structure context/content"/>

First, you will see that we enclose everything in a macro (named master) with this code:

<metal:block define-macro="master">

Then we want to print the title and the content of the page. The page itself is available in the template via a binding called context. Among its attributes, we can use meta, which is a mapping that holds all metadata of the page: its title, keyword, description and all specific metadata that you could define in your reStructuredText source file. We can therefore print the title of the page with this simple piece of code:

<h1 tal:content="context/meta/title"/></h1>

As for the content itself, it is available through another binding of context, quite appropriately called content:

<tal:content tal:replace="structure context/content"/>

First run

As we are already equipped with reStructuredText source files and a template, we have all we need to build a first version of our site:

$ pwd
$ ls -R        src

gnu.jpg         index.txt       install.html

Simply run soho without any command-line options:

$ soho
(...)     Begin building web site.
(...)     Creating new directory: "www"
(...)     Copying file "src/gnu.jpg" to "www/gnu.jpg".
(...)     Processing "src/index.txt" (writing in "www/index.html").
(...)     Processing "src/install.rst" (writing in "www/install.html").
(...)     Web site has been built.

As you can see, Soho has processed our reStructuredText files and generated corresponding HTML files (in a directory it has created, since it did not exist). As for the image, since it is not a reStructuredText file, Soho has simply copied it to the output directory:

$ ls -R        src                     www

gnu.jpg         index.txt       install.rst

gnu.jpg         index.html      install.html


We could have told Soho to use another source directory, another output directory or another template. We could also have asked Soho to ignore certain files. See usage for a comprehensive reference of the possible options.

If you try to run Soho again, you will see that it will ignore files that have not changed:

$ soho
(...)     Begin building web site.
(...)     Ignoring "src/gnu.jpg" because previously generated file seems to be up to date.
(...)     Ignoring "src/index.txt" because previously generated file seems to be up to date.
(...)     Ignoring "src/install.rst" because previously generated file seems to be up to date.
(...)     Web site has been built.

However, running it with the -f command-line option forces the processing of all source files:

$ soho -f
(...)     Begin building web site.
(...)     Creating new directory: "www"
(...)     Copying file "src/gnu.jpg" to "www/gnu.jpg".
(...)     Processing "src/index.txt" (writing in "www/index.html").
(...)     Processing "src/install.rst" (writing in "www/install.html").
(...)     Web site has been built.


You probably have open these HTML files in a browser. Everything seems fine, though there is a problem with the link from the index page to the installation page. Indeed, we have indicated a link to install.txt because that is the name of the source file. This is convenient if you read the source files. However, the link in the generated HTML is broken.

Hopefully, Soho has a feature called "filters". It lets you change the text of the source file before or after it is processed, among other things. To do that, simply create a file named and put it in our

from soho.filters import changeLinksFromTxtToHTML, replaceXHTMLShortTags

pre_filters = (changeLinksFromTxtToHTML, )

Here we simply use a built-in filter.

If we regenerate our site (with the -f option), we will see that our link now correctly points to the HTML page.


The filters chapter goes further into this feature: it presents the different types of filters, all built-in filters, how to define your own filters, etc.



What to do now?

I hope this tutorial has shown how simple Soho is to use. You may want to read more about the command-line options and the (optional) configuration file in the usage page. Filters and bindings also have their own chapter.