reStructuredText and docutils

Lightning Talk

Author: Beni Cherniavsky
Date: 2006-02-27
Based on:cheatsheet.txt by David Goodger

reStructuredText (a.k.a. reST or rST)

A very simple and readbale format for writing documents in plain text. Grew from quest for Python docstring format but useful for all kinds of docs.

Structure elements

Indented block quotes
  • Bullet lists
    1. Enumerated lists
Term
Definition lists
field name:Field lists

Literal blocks

| Line block preserves the lines;
|   It's good for text that rhymes.

Directives

Verbose but extensible markup

This is a directive. There are many directives for various arcane needs.

Link markup

There is a rich link markup syntax. Think of _ as a right-pointing-arrow. To reduce clutter in text, most [1] links have

outside the text. See specification for details.

[1]Use inline sparingly.

Inline Markup

I can't emphasize PEP 666 strongly enough. I'll just rm -rf / in frustration. I'll then pretend to be a happy monkey.

That's the idea on one leg; now go and learn...

Docutils

Docutils is a Python project developing tools that convert reST to various formats. It also defines the evolving reST format.

Features

  • Parser from reST to internal document tree.

  • Writers to HTML4+CSS1, S5 [*], LaTeX.

  • Command-line tools:

    rst2latex.py [options] doc.txt doc.tex
buildhtml.py [options] top-directory/

  • Elaborate configuration system. Easy to tweak output style.

  • Lots of detailed documentation (guess in what format).

  • Internationalized quite well..

  • Public domain.

[*]S5 is an HTML+CSS+javascript presentation system by Eric Meyer. You've seen it in several lectures at this conference. On my laptop it's too slow for a lightning talk; less in a terminal is just right ;-).

Project

Started and led by David Goodger. Felix Wiemann very active for a long time now. Contributions by >100 people over time (but <10 active at once).

Minimal barriers to entry. SVN access given easily (get yours today!). Work in the sandbox and/or on a branch if you don't want responsibility.

Docs and tests kept in sync. SVN head practically almost stable. Rare releases so far.

License:Public Domain

Sandbox

  • Converters from forms of HTML.
  • Experimental writers for OpenDocument, PDF, Python documentation LaTeX dialect, etc...
  • Workflows for things like XSL-FO.
  • Hacks for things like frames or math support.
  • Added directives.
    • Latest coolness: ASCII Art -> SVG conversion directive.

Hebrew

  • Directives and such can be translated (lazy me will do it soon).
  • Few words in the syntax so it's RTL/LTR friendly.
  • Implicit RTL/LTR assignment on the output works well (lazy me will release it soon).

Other reST tools

  • Perl reST parser by Mark Nodine -- long maintained in-house, recently released (in docutils SVN). "There is more than one language to parse it" ;-).
  • Impressive modes for Emacs and Vim7.
  • Couple of GUI tools for editing with preview.

Users