Introduction

Most rest2web configuration is done through the config file. It is generally easier to edit a single text file than to have to remember lots of arcane command line options.

There are several things you can control from the command line. These include :

• The Config File
• The verbosity level (how much information rest2web outputs as it runs
• Override the template file
• Go into force mode
• Specify global uservalues

Basic Usage

If you type r2w.py --help at the command line, this is the message it should print :

usage: r2w.py [options] config_file

options:
  --version             show program's version number and exit
  -h, --help            show this help message and exit
  -v                    Verbose output (default).
  -a                    Display warnings & actions only.
  -w                    Display warnings only.
  -t TEMPLATE, --template-file=TEMPLATE
                        Specify a template file. (Overrides first template.)
  -u USERVALUES, --uservalues=USERVALUES
                        Global uservalues for the site, in the form
                        "name=value".
  -f, --force           Force site without indexes, restindexes or template.
  -n, --nopause         Do not pause after processing (overrides setting in config file).
  -s, --skiperrors      Skip errors (continue processing).

The Config File

If you run r2w.py without any command line options, it looks for a file called r2w.ini in the current working directory.

Alternatively you can specify a config file as the last argument to r2w.py.

Verbosity Level

By default rest2web outputs a lot of information about what it does. This includes which directories and files it is processing, as well any errors raised along the way.

This may be too much information. There are three different verbosity levels :

• -v - Verbose, the default level. Information, actions and errors.
• -a - Action level. Actions and errors only.
• -w - Warning level. Warnings only.

Template File

rest2web uses template files to generate the output pages. See Templating for the details of this.

Often you will only use a single template, specified in the restindex of your top level index page. Sometimes you may want to use alternative templates for the same site. For example one for the online version and one for the distributed documentation.

You can override the top level template from the command line, using either :

r2w.py -t path/to/template.txt

r2w.py --template-file=path/to/template.txt

Uservalues

The Uservalues are a way of providing values to use in your content and templates. They can be useful for multiple translations, or for values that you want to specify at the time you build your site.

You can specify uservalues in the restindex of each page. You can also specify global uservalues (available in every page) in the config file, or at the command line.

If you specify the same values in your config file and at the command line, the command line takes higher priority.

A uservalue needs a name (this is how you refer to it in pages/templates) and a value. The name and value should be separated by an equals sign.

This means that you can specify uservalues at the command line using either :

r2w.py -u "name=value"

r2w.py --uservalues="name=value"

The double quotes are optional, but useful if the value has spaces.

Uservalues in pages will override global uservalues specified in either the config file or at the command line.

Force Mode

force mode allows you to build websites without specifying a template, providing indexes, or having restindexes in the ReST documents that form your pages.

You can supply any of these that you want, but where they are missing rest2web will supply defaults.

To switch force mode onfrom the command line, use :

r2w.py -f

r2w.py --force

No Pause

This overrides the 'pause' option in the config file, and forces 'r2w.py' to not pause after running.

skiperrors

This option determines how rest2web will handle exceptions (like our old friend UnicodeDecodeError) that happen when processing pages.

If set, rest2web will display the error and move to the next file. The default is off.