What is rest2web ?

rest2web is a tool for autogenerating wesites, or parts of websites. It's main features are :

• Integrated with docutils.
• Automatically builds index pages and navigation links (sidebars and breadcrumbs).
• Embedded code in templates for unlimited expressiveness.
• Flexible macro system.
• Uses relative links, so sites can be viewed from the filesystem.
• Unicode internally - so you don't have to be.
• Includes features for multiple translations of sites.
• Built-in gallery creator plugin.
• The basic system is very easy to use.
• Lots of powerful (optional) features.

The content can be stored as HTML, or in ReST format; in which case the HTML will be generated using docutils. rest2web inserts each page into a template, and automatically creates index pages for sections, and navigation links.

ReST is a WYSIWYG text markup format. It is simpler than HTML - but very flexible. A document marked up with reST is still readable as text. This means that maintaining article contents in reST is a lot easier than maintaining them in HTML.

Adding new pages is as easy as dropping a text file into the right folder. rest2web builds the new page and adds a link to it in the index (optionally with a description as well). Removing a page is just as easy. Delete the file, and when you run rest2web again it removes the entry.

rest2web includes standard functions to build a sidebar, with links to the other pages in the directory, or to the other sections in the website.

Another advantage is that a website can be easily restyled by only changing template files. It is likely that only a few template files will be needed for most websites [1].

Because rest2web generates sites using relative paths, the results can be viewed from the filesystem. This means that it is an effective way of bundling documentation.

A rest2web Site

rest2web is optimized for creating websites with a particular structure. It is aimed at the sort of sites that have sections and subsections. The basic structure is closely related to the directory structure on disk. It is based on having an index page in each directory. Files in that directory are listed in the index page, which can be divided into various sections.

Subdirectories have their own index page - that index page will be link to from the 'directory' above. Your website structure is modelled on the directory structure. This is the hierarchy of sections and subsections.

Every text file ('.txt' extension) in a directory will be scanned. If the file starts with a restindex, then it will be processed.

If you want links to some prebuilt files on an index page, then you can put a relevant text file in the directory with the details (target name, link title, page description, etc) and set build: No. This allows you to use rest2web to just build part of a website - but still include in the index pages that it doesn't build. [2]

For a good introduction, read the tutorial - Creating a Site. You can also peruse the Test Site included with this documentation. It illustrates most features of rest2web.

Every page can also have a set of uservalues that will be inserted into the template. This is another way of putting dynamic values into a template. An obvious use of this system is for providing a website in several different languages.

If you just want to get up and running, you may want to checkout the Quick Start Guide by Andrew Ittner.

Downloading

All distributions include all the documentation and the example site.

Installing

If you are running the source version of rest2web, you need docutils installed. It works best with the latest version [5].

rest2web itself shouldn't actually need installing. You can place the 'rest2web' directory in your 'site-packages' folder if you want to. You should then be able to run 'r2w.py' from anywhere.

You can test rest2web by just double clicking on it. This should build the docs and example site as html, in the docs_html directory. It will generate a log of the process in 'log.txt'. If there are any problems then they will be recorded in the log. Please report any bugs to the rest2web Mailing List.

The files in the 'modules' folder are used by macros. They will also need to be somewhere on sys.path (e.g. in 'site-packages'.) Alternatively, if the modules directory is in the same directory as 'r2w.py' when you run it, it will automatically be added to the path.

Useful Links

• rst-ht2html - This is a project with a similar aim, the automatic creation of websites from restructured text. It uses ht2html, the scripts that generate sites like Python.org, and Jython.org. rest2web is more flexible with the templating it allows. It should be possible to generate a much wider range of sites with rest2web.

• docutils - this is the Python project that turns reStructuredText into nice XHTML.

• Firedrop2 - the blog client originally created by Hans Nowak.

  This project [6] produced embedded_code.py and textmacros.py which are used by rest2web. embedded_code.py is the templating engine used by rest2web. textmacros.py adds a simple system of macros into rest2web.

  Firedrop2 also supports alternative text markups sextile and textile. rest2web may be enhanced to support these (if there is any demand).

  Note

  I now maintain Firedrop2. You can download the latest distribution, and browse the docs over at : http://www.voidspace.org.uk/python/firedrop2/index.shtml.

• webgen - A ruby project that does a similar thing to rest2web. It is scarily similar in the way it works. It doesn't work with ReST markup however.

• Tahchee - an alternative to rest2web that uses the cheetah templating system.

Footnotes