reStructuredText: Plain-text with superpowers

Slides at catherinedevlin.pythoneers.com

Problem

FOSS documenation is terrible.

How bad?

Almost as bad as proprietary!

Why?

Labor of love

reStructuredText

Love to document

Stylesheet revolution

Presentation

content

Where's our revolution?

To create a document

Classic workflow

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

reStructuredText

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

Flexible, formatted results from simple plaintext

ex1.rst

======
PyCon_
======

Annual conference
-----------------

A *community-organized* Python conference

* World's largest ( ~ 1000 attendees)

* Worldwide draw of community leaders

* Affordable

.. _pycon: us.pycon.org

Workflow with reStructuredText

Plain-text rocks anyway

• Editors galore
• Human-readable
• Unix-fu
• Version control
• Script it

What about LaTeX?

A \emph{community-organized} Python conference
\begin{itemize}
\item {}
World's largest ( {\textasciitilde} 1000 attendees)

\item {}
Worldwide draw of community leaders

\item {}
Affordable

\end{itemize}

\end{document}

"I still prefer LaTeX"

Fine, be that way.

How flexible?

• rst2html
• rst2xml
• rst2pseudoxml
• rst2latex
• rst2s5

Beyond docutils

• rst2pdf
• rst2odt (OpenOffice Writer)
• rst2odp (OpenOffice Impress)
• Sphinx (advanced doc tree)
• rest2web (complex websites)
• rst2man (UNIX man pages)
• rst2chm (Windows help pages)
• nabu (RDBMS rows)

Also recognized by

• epydoc
• wikis: MoinMoin, zwiki, StikiWiki
• WordPress blogs (with plugin)
• Crunchy Python tutorials
• Trac
• Plone, Zope
• emacs, vim, Komodo

And there's more...

More converters, importers, etc.

Docutils link list

Let's do this

It came from Pythonland

David Goodger, maker of reStructuredText

Styles

Styles

rst2html --stylesheet=

rst2pdf --stylesheets=

rst2s5 --theme-url=ui/mytheme

rst2odt --stylesheet=

rst2latex --stylesheet=

Editors

• Enthought Tool Suite's rsteditor
• Online editor at cometdemo.lshift.net:8080
• editor packed with Crunchy (trunk)
• And more...

Installation

sudo aptitude update
sudo aptitude install python-dev python-setuptools
sudo easy_install docutils
# stop here if you like
sudo aptitude install python-vtk rst2pdf python-odt rst2man
sudo easy_install sphinx rst2pdf odtwriter
# for rsteditor
sudo aptitude install python-dev python-qt4
sudo easy_install -U numpy
sudo easy_install -U TraitsBackendQt[nonets] AppTools[nonets]

No-install alternative

rst2a.com

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

Go forth

• See these slides at catherinedevlin.pythoneers.com
• Document some code
• Docutils link list
• docutils mailing lists
• Write your Mom