rest2web: Building Websites Across the Known Universe

Introduction to rest2web

A Gentle Introduction to the Site Builder

A rest2web Site

emoticon:firefox 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. Cool

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. [1]

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.


emoticon:file1 All distributions include all the documentation and the example site.

Source Distribution

rest2web is a pure Python programme. If you have Python installed you don't need to compile anything to use the source distribution.

Download restweb (1.9mb) from rest2web-0.4.0alpha.zip

Executable Distribution

Download the executable version of restweb (3.5mb) from rest2web-0.4.0alpha-EXE.zip

Subversion Repository

You can browse (or download using SVN) the latest development version over at the SVN Repository. [2]

The version in SVN is often more up to date than the latest release version - and I try not to break the version in SVN (but no guarantees).

The full command is : svn co https://svn.rest2web.python-hosting.com/trunk/ [3]


rest2web can also be downloaded from the Sourceforge rest2web Project Page.


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

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 'rest2web.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.

rest2web uses the Pythonutils module. This has the modules for reading the config file and generating the log etc. rest2web comes with these modules included. If you install Pythonutils properly, then you can delete the pythonutils folder from your distribution.

At the Heart

rest2web and docutils are both projects written in a language called Python. In order to use the source version you will need Python installed.


If you don't want to (or can't) install Python, then you can use the pre-built executable version instead.

This does limit slightly what you can do with macros and embedded code in the templates. (Basically you can only use the modules that come included or that you create yourself).

The templates and macros are also done using Python code. If you've never used Python before, don't let this put you off. It's a very easy language to learn and you can learn the basics very quickly. The main Python website has distributions for most platforms available for download, as well as links to tutorials and resources for learning Python.

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 [5] 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).


    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. Cool

  • webgen - A ruby project that does a similar thing to rest2web. It was started at around the same time as rest2web, and is scarily similar in the way it works. Laughing I only saw it a few weeks ago though, and it doesn't work with reST makup..

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


[1]Many websites will only need a single template file. Voidspace actually uses two for all the parts of the site built by rest2web.
[2]It's possible to include details of several of these pages in a single file called 'restindex.txt'. It is basically a series of restindexes in a single file.
[3]Many thanks to the decent folks over at python-hosting.com.
[4]For Windoze users, I recommend the SVN client TortoiseSVN.
[5]Version 0.3.9 or later.
[6]And Kaa, the predecessor to firedrop.

Return to Top
Part of the rest2web Docs
Page last modified Thu Mar 30 17:04:24 2006.

Site Built with rest2web SourceForge.net Logo Certified Open Source

Python on Voidspace