Author: David Goodger
Date: 2017-01-04

# Docutils Front-End Tools

Author: | David Goodger
Contact: | docutils-develop@lists.sourceforge.net
Revision: | 8012
Date: | 2017-01-04
Copyright: | This document has been placed in the public domain.

Contents

- Introduction
  - Getting Help
- The Tools
  - HTML-Generating Tools
    - buildhtml.py
    - rst2html.py
    - rst2html4.py
      - Stylesheets
    - rst2html5.py
    - rstpep2html.py
    - rst2s5.py
      - Themes
  - LaTeX-Generating Tools
    - rst2latex.py
    - rst2xetex.py
  - XML-Generating Tools
    - rst2xml.py
  - ODF/OpenOffice-Generating Tools
    - rst2odt.py
  - reStructuredText-Generating Tools
  - Testing/Debugging Tools
    - rst2pseudoxml.py
    - quicktest.py
- Customization
  - Command-Line Options
  - Configuration Files

# Introduction

Once the Docutils package is unpacked, you will discover a "`tools`" directory containing several front ends for common Docutils processing. Rather than a single all-purpose program, Docutils has many small front ends, each specialized for a specific "Reader" (which knows how to interpret a file in context), a "Parser" (which understands the syntax of the text), and a "Writer" (which knows how to generate a specific data format).

Most front ends have common options and the same command-line usage pattern:

    toolname [options] [<source> [<destination]]

(The exceptions are buildhtml.py and rstpep2html.py.) See rst2html.py for concrete examples. Each tool has a "`--help`" option which lists the command-line options and arguments it supports. Processing can also be customized with configuration files.

The two arguments, "source" and "destination", are optional. If only one argument (source) is specified, the standard output (stdout) is used for the destination. If no arguments are specified, the standard input (stdin) is used for the source.

## Getting Help

First, try the "`--help`" option each front-end tool has.

Users who have questions or need assistance with Docutils or reStructuredText should post a message to the Docutils-users mailing list.

# The Tools

## HTML-Generating Tools

### buildhtml.py

Readers: | Standalone, PEP
Parser: | reStructuredText
Writers: | html, pep_html

Use `buildhtml.py` to generate `*.html` from all the `*.txt` files (including PEPs) in each <directory> given, and their subdirectories too. (Use the `--local` option to skip subdirectories.)

Usage:

    buildhtml.py [options] [<directory> ...]

After unpacking the Docutils package, the following shell commands will generate HTML for all included documentation:

    cd docutils/tools
    buildhtml.py ..

For official releases, the directory may be called "docutils-X.Y", where "X.Y" is the release version. Alternatively:

    cd docutils
    tools/buildhtml.py --config=tools/docutils.conf

The current directory (and all subdirectories) is chosen by default if no directory is named. Some files may generate system messages (docs/user/rst/demo.txt contains intentional errors); use the `--quiet` option to suppress all warnings. The `--config` option ensures that the correct settings are in place (a `docutils.conf` configuration file in the current directory is picked up automatically). Command-line options may be used to override config file settings or replace them altogether.

### rst2html.py

Reader: | Standalone
Parser: | reStructuredText
Writer: | html

rst2html.py is the front-end for the default Docutils HTML writer. The default writer may change with the development of HTML, browsers, Docutils, and the web. Currently, it is html4css1.

- Use rst2html.py, if you want the output to be up-to-date automatically.
- Use a specific front end, if you depend on stability of the generated HTML code, e.g. because you use a custom style sheet or post-processing that may break otherwise.

### rst2html4.py

Reader: | Standalone
Parser: | reStructuredText
Writer: | html4css1

The `rst2html4.py` front end reads standalone reStructuredText source files and produces XHTML 1.0 Transitional output. A CSS stylesheet is required for proper rendering; a simple but complete stylesheet is installed and used by default (see Stylesheets below).

For example, to process a reStructuredText file "`test.txt`" into HTML:

    rst2html.py test.txt test.html

Now open the "`test.html`" file in your favorite browser to see the results. To get a footer with a link to the source file, date & time of processing, and links to the Docutils project, add some options:

    rst2html.py -stg test.txt test.html

#### Stylesheets

`rst2html.py` inserts into the generated HTML a cascading stylesheet (or a link to a stylesheet, when passing the "`--link-stylesheet`" option). A stylesheet is required for proper rendering. The default stylesheet (`docutils/writers/html4css1/html4css1.css`, located in the installation directory) is provided for basic use. To use different stylesheet(s), specify the stylesheets' location(s) as comma-separated list with the "`--stylesheet`" (for a URL) or "`--stylesheet-path`" (for a local file) command-line option, or with configuration file settings (e.g. `./docutils.conf` or `~/.docutils`). To experiment with styles, please see the guide to writing HTML (CSS) stylesheets for Docutils.

### rst2html5.py

Reader: | Standalone
Parser: | reStructuredText
Writer: | html5 (html5_polyglot)

The `rst2html5.py` front end reads standalone reStructuredText source files and produces HTML 5 output. Correct rendering of elements not directly supported by HTML depends on a CSS style sheet. The provided style sheets `minimal.css` and `plain.css` define required and optional styling rules respectively.

### rstpep2html.py

Reader: | PEP
Parser: | reStructuredText
Writer: | pep_html

`rstpep2html.py` reads a new-style PEP (marked up with reStructuredText) and produces XHTML 1.0 Transitional. It requires a template file and a stylesheet. By default, it makes use of a "`pep-html-template`" file and the "`pep.css`" stylesheet (both in the `docutils/writers/pep_html/` directory), but these can be overridden by command-line options or configuration files.

For example, to process a PEP into HTML:

    cd <path-to-docutils>/docs/peps
    rstpep2html.py pep-0287.txt pep-0287.html

### rst2s5.py

Reader: | Standalone
Parser: | reStructuredText
Writer: | s5_html

The `rst2s5.py` front end reads standalone reStructuredText source files and produces (X)HTML output compatible with S5, the "Simple Standards-based Slide Show System" by Eric Meyer. A theme is required for proper rendering; several are distributed with Docutils and others are available; see Themes below.

For example, to process a reStructuredText file "`slides.txt`" into S5/HTML:

    rst2s5.py slides.txt slides.html

Now open the "`slides.html`" file in your favorite browser, switch to full-screen mode, and enjoy the results.

#### Themes

Each S5 theme consists of a directory containing several files: stylesheets, JavaScript, and graphics. These are copied into a `ui/<theme>` directory beside the generated HTML. A theme is chosen using the "`--theme`" option (for themes that come with Docutils) or the "`--theme-url`" option (for themes anywhere). For example, the "medium-black" theme can be specified as follows:

    rst2s5.py --theme medium-black slides.txt slides.html

The theme will be copied to the `ui/medium-black` directory.

Several themes are included with Docutils:

`default`

  This is a simplified version of S5's default theme.

  Main content: | black serif text on a white background
  Text capacity: | about 13 lines
  Headers: | light blue, bold sans-serif text on a dark blue background; titles are limited to one line
  Footers: | small, gray, bold sans-serif text on a dark blue background

`small-white`

  (Small text on a white background.)

  Main content: | black serif text on a white background
  Text capacity: | about 15 lines
  Headers: | black, bold sans-serif text on a white background; titles wrap
  Footers: | small, dark gray, bold sans-serif text on a white background

`small-black`

  Main content: | white serif text on a black background
  Text capacity: | about 15 lines
  Headers: | white, bold sans-serif text on a black background; titles wrap
  Footers: | small, light gray, bold sans-serif text on a black background

`medium-white`

  Main content: | black serif text on a white background
  Text capacity: | about 9 lines
  Headers: | black, bold sans-serif text on a white background; titles wrap
  Footers: | small, dark gray, bold sans-serif text on a white background

`medium-black`

  Main content: | white serif text on a black background
  Text capacity: | about 9 lines
  Headers: | white, bold sans-serif text on a black background; titles wrap
  Footers: | small, light gray, bold sans-serif text on a black background

`big-white`

  Main content: | black, bold sans-serif text on a white background
  Text capacity: | about 5 lines
  Headers: | black, bold sans-serif text on a white background; titles wrap
  Footers: | not displayed

`big-black`

  Main content: | white, bold sans-serif text on a black background
  Text capacity: | about 5 lines
  Headers: | white, bold sans-serif text on a black background; titles wrap
  Footers: | not displayed

If a theme directory contains a file named `__base__`, the name of the theme's base theme will be read from it. Files are accumulated from the named theme, any base themes, and the "default" theme (which is the implicit base of all themes).

For details, please see Easy Slide Shows With reStructuredText & S5.

## LaTeX-Generating Tools

### rst2latex.py

Reader: | Standalone
Parser: | reStructuredText
Writer: | latex2e

The `rst2latex.py` front end reads standalone reStructuredText source files and produces LaTeX output. For example, to process a reStructuredText file "`test.txt`" into LaTeX:

    rst2latex.py test.txt test.tex

The output file "`test.tex`" should then be processed with `latex` or `pdflatex` to get a document in DVI, PostScript or PDF format for printing or on-screen viewing.

For details see Generating LaTeX with Docutils.

### rst2xetex.py

Reader: | Standalone
Parser: | reStructuredText
Writer: | xetex

The `rst2xetex.py` front end reads standalone reStructuredText source files and produces LaTeX output for processing with unicode-aware TeX engines (LuaTeX or XeTeX). For example, to process a reStructuredText file "`test.txt`" into LaTeX:

    rst2xetex.py test.txt test.tex

The output file "`test.tex`" should then be processed with `xelatex` or `lualatex` to get a document in PDF format for printing or on-screen viewing.

For details see Generating LaTeX with Docutils.

## XML-Generating Tools

### rst2xml.py

Reader: | Standalone
Parser: | reStructuredText
Writer: | XML (Docutils native)

The `rst2xml.py` front end produces Docutils-native XML output. This can be transformed with standard XML tools such as XSLT processors into arbitrary final forms. An example is the xml2rst processor in the Docutils sandbox.

## ODF/OpenOffice-Generating Tools

### rst2odt.py

Reader: | Standalone
Parser: | reStructuredText
Writer: | ODF/.odt

The `rst2odt.py` front end reads standalone reStructuredText source files and produces ODF/.odt files that can be read, edited, printed, etc with OpenOffice `oowriter` (http://www.openoffice.org/). A stylesheet file is required. A stylesheet file is an OpenOffice .odt file containing definitions of the styles required for `rst2odt.py`. You can learn more about how to use `rst2odt.py`, the styles used `rst2odt.py`, etc from Odt Writer for Docutils.

## reStructuredText-Generating Tools

Currently, there is no reStructuredText writer in Docutils and therefore an `rst2rst.py` tool is still missing.

To generate reStructuredText documents with Docutils, you can use the XML (Docutils native) writer and the xml2rst processor.

## Testing/Debugging Tools

### rst2pseudoxml.py

Reader: | Standalone
Parser: | reStructuredText
Writer: | Pseudo-XML

`rst2pseudoxml.py` is used for debugging the Docutils "Reader to Transform to Writer" pipeline. It produces a compact pretty-printed "pseudo-XML", where nesting is indicated by indentation (no end-tags). External attributes for all elements are output, and internal attributes for any leftover "pending" elements are also given.

### quicktest.py

Reader: | N/A
Parser: | reStructuredText
Writer: | N/A

The `quicktest.py` tool is used for testing the reStructuredText parser. It does not use a Docutils Reader or Writer or the standard Docutils command-line options. Rather, it does its own I/O and calls the parser directly. No transforms are applied to the parsed document. Various forms output are possible:

- Pretty-printed pseudo-XML (default)
- Test data (Python list of input and pseudo-XML output strings; useful for creating new test cases)
- Pretty-printed native XML
- Raw native XML (with or without a stylesheet reference)

# Customization

## Command-Line Options

Each front-end tool supports command-line options for one-off customization. For persistent customization, use configuration files. Command-line options take priority over configuration file settings.

Use the "--help" option on each of the front ends to list the command-line options it supports. Command-line options and their corresponding configuration file entry names are listed in the Docutils Configuration Files document.

## Configuration Files

Configuration files are used for persistent customization; they can be set once and take effect every time you use a front-end tool.

For details, see Docutils Configuration Files.