[Rest2web-develop] rest2web Changes

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

{ran_emo} There have been several fairly major changes to `rest2web <http://www.voidspace.org.uk/python/rest2web/>`_ in `subversion <http://svn.rest2web.python-hosting.com>`_.

* The restindex and uservalues for a page (the page metadata basically) can now be in a ReST comment. This means your website source documents can now be valid ReST documents as well.
* The macro system has been changed to make it easier to use. (All the standard macros are now built-in).
* In force mode (where rest2web will render documents with no metadata) rest2web no longer *requires* a config file. {sm;:-)}

More details below.

There are also (at least) three more sites online that have been created with rest2web :

* `German Website on Text Based Tools <http://www.automatisch.cc/>`_
* `Aikido Club Website <http://www.aikido-verein-hannover.de/>`_
* `Martin Krafft's PHD Pages <http://martin-krafft.net/phd/>`_

.. raw:: html

    {title;restindex inside comment;3}

This change is quite simple, but it means that all your website pages can also be valid ReST documents.

You can now put the restindex and uservalues inside a ReST comment : ::

    ..
        restindex
            # values
        /restindex

        uservalues
            # values
        /uservalues

This means that your pages can still contain the rest2web metadata, but also be rendered by `docutils <http://docutils.sourcdeforge.net>`_ individually.

.. raw:: html

    {title;Changes to the Macro System;3}

The restweb `Macro System <http://wwwv.voidspace.org.uk/python/rest2web/macros.html>`_ has been simplified.

All the standard macros have been moved into the rest2web package, along with the support modules they need.

You can still supply your own macros, in the same way as before, by specifying a macros file in your site `Config File <http://wwwv.voidspace.org.uk/python/rest2web/macros.html>`_. This can override any of the built in macros if you wish. {sm;:-)}

Two of the standard macros (``smiley`` and ``emoticon``) need to be configured with the URL path to the directory containing the images. If you are using a smiley set other than the one supplied with rest2web, the ``smiley`` macro will also need to know the path to the directory containing the smiley images.

You can configure these by supplying them in a ``Macro Paths`` section in your site config file. Shown below with the defaults which are used if you *don't* include these values : ::

    [Macro Paths]    
    smiley_directory  = ''
    smiley_url = '<% path_to_root %>images/smilies/'
    emoticon_url = '<% path_to_root %>images/'

A blank value for ``smiley_directory`` means use the standard smiley set. {sm;:-)}

This change is fully 'backwards compatible' with the old system though. Config files and macro files from before the change will continue to work in the same way.

.. raw:: html

    {title;Config File and Force Mode;3}

If rest2web is used in `Force Mode <http://wwwv.voidspace.org.uk/python/rest2web/force_mode.html>`_, it can create a website from a directory (tree) of ReST documents with no metadata. It will even auto-build index pages for directories.

It now no longer *requires* a site config file to specify the source and target directories. Simply run ``r2w.py -f``, with no ``r2w.ini`` file.

rest2web will start looking for ReST source documents in the current directory. It will create the HTML files in a subdirectory 'html'. (Which means that text files in this directory *won't* be scanned.)

You *might* not like the default template for force mode. (On the other hand you might like it very much, it is based on the template used to create the rest2web_ site.)

If you want something more minimalistic, you can replace the file ``rest2web/defaults/template.txt`` with something like : ::

    <html>
    <head>
        <title><% title %></title>
        <meta http-equiv="Content-Type" content="text/html; charset=<% final_encoding %>">
        <link rel="stylesheet" href="/stylesheets/docutils.css" type="text/css">
    </head>
    <body>
        <% body %>
    </body>    
    </html>

This won't include the breadcrumbs or navigation sidebar, but these are easy to add. {sm;:biggrin:}