reStructuredText: Plain Text Gets Superpowers

Quit Scribbling Notes

Slides at http://catherinedevlin.pythoneers.com

Outlines are boring

• The concept
• Quick reST syntax
• Installation & Tools
• Sphinx
• Customization

The Concept

Or, Why You Are Here

Kathy Sierra

Problem

Nobody uses your (favorite) stuff

Reason

Your docs stink

Python web frameworks

• Zope
• TurboGears
• Django
• Pylons
• Web2Py

Reason₂

Programming is a labor of love

You hate writing docs

Solution

You used to hate writing docs

Stylesheet revolution

Separate Presentation from content

Where's our revolution?

To create a document

Classic workflow

• Many skills
• Errors and omissions
• Makes you bitter, cynical

reStructuredText

  Plain-text conventions
+ conversion programs
------------------------
  pretty much anything

Flexible, formatted results from simple plaintext

Expert help available

example

==================================
My Amiga is better than your Atari
==================================

The Amiga 2000 is the *most powerful*
computer you can imagine.  It is the **ULTIMATE**!

Specs
-----

========= ==============
RAM       512 KB
CPU speed 7.14 MHz
display   640x400 pixels
========= ==============

Workflow with reStructuredText

Plain-text rocks anyway

• Tools galore
• Human-readable
• Unix-fu / Powershell-fu
• Version control
• Script it

What about LaTeX?

\title{My Amiga is better than your Atari%
  \phantomsection%
  \label{my-amiga-is-better-than-your-atari}}

The Amiga 2000 is the \emph{most powerful}
computer you can imagine.  It is the \textbf{ULTIMATE}!

\section*{Specs%
  \phantomsection%
  \addcontentsline{toc}{section}{Specs}%
  \label{specs}%
}

"I still prefer LaTeX"

Fine, be that way.

How flexible?

• rst2html
• rst2xml
• rst2pseudoxml
• rst2latex
• rst2s5

Separate installs

• rst2pdf
• rst2odt (OpenOffice Writer)
• rst2odp (OpenOffice Impress)
• Wikir (Wiki syntax)
• rst2qhc (Qt Help files)
• rst2man (UNIX man pages)

Advanced stuff

• Sphinx (advanced doc tree)
• rest2web (complex websites)
• nabu (RDBMS rows)

Also recognized by

• epydoc
• MediaWiki
• MoinMoin wiki (#format rst)
• WordPress blogs (with plugin)
• Crunchy Python tutorials
• Pandoc
• Trac

Let's do this

Quick reST Syntax

It came from Python

David Goodger, maker of reStructuredText

Tools & Installation

Editor support

• emacs: rst.el
• vim plugin
• jed rst mode
• TextMate bundle
• gedit plugin

WYSIWYG Editors

• Crunchy's rst_edit
• Enthought Tool Suite's rsteditor
• Online editor at cometdemo.lshift.net:8080

Installation

aptitude install python-dev / yum install python-devel
http://pypi.python.org/pypi/setuptools
easy_install -UZ docutils

easy_install -UZ sphinx
easy_install -UZ rst2pdf rst2man

Editor installation

Crunchy

download, unzip

Enthought Tool Suite

aptitude install python-numeric python-qt4
easy_install -U TraitsBackendQt[nonets] AppTools[nonets]

Consider Enthought Python Distribution

rst2a.com: no-install alternative

Sphinx

Creates advanced documentation tree.

1. sphinx-quickstart
2. fill out toctree (Table of Contents)
3. Write .rst docs for the contents
4. make html or sphinx-build

Customization

Styles

Styles

rst2html --stylesheet=

rst2pdf --stylesheets=

rst2s5 --theme-url=ui/mytheme (edit ui/mytheme/pretty.css)

rst2odt --stylesheet=

Sphinx themes

In conf.py:

• html_theme
• html_theme_options

http://sphinx.pocoo.org/theming.html

Custom Roles

.. role:: weird (emphasis)
   :class: crazy

That reST talk was :weird:`interesting`.

.crazy {color: green; font-family: cursive;}

That reST talk was interesting.

Code-based customization

• Jeff Rush's PyCon Talk at blip.tv
• Writing custom roles
• Writing custom directives

Your own reST-based tools

• Framework is extensively extensible
• Jeff Rush's PyCon Talk at blip.tv
• Consider using XML output

Go write

Document your code

Document other people's code

Write your mom

Questions?