reStructuredText (reST) è un linguaggio di markup nato per la documentazione di codice Python ed è utilizzato sia nelle docstring sia in documenti separati. La sua semplicità lo ha reso tuttavia simpatico anche a parecchi sviluppatori che usano altri linguaggi; è ormai piuttosto comune imbattersi in un README.rst mentre si guarda qualche progetto su GitHub.

Il formato reST

Un documento reST è suddiviso in paragrafi. Il paragrafo non è altro che un blocco di testo separato da una o più linee vuote.

Primo paragrafo.

Secondo paragrafo

All’interno di ciascun paragrafo è possibile marcare del testo come corsivo mettendolo tra singoli asterischi, come grassetto mettendolo tra doppi asterischi e con carattere a spaziatura fissa mettendolo tra due coppie di apici inversi.

*corsivo*

**grassetto**

``spaziatura fissa``

È possibile ottenere delle liste puntate facendo iniziare il paragrafo con un asterisco e usando l’indentazione in modo appropriato qualora un elemento della lista sia su più linee.

* Primo elemento
* Secondo elemento
  suddiviso su due linee

Le liste numerate invece si ottengono… con i numeri (si noti come ogni numero deve essere seguito dal punto).

1. Primo elemento
2. Secondo elemento

I titoli invece sono contradistinti da una “sottolineatura”. Ad esempio, le sezioni sono sottolineate con il carattere =, le sottosezioni col segno meno.

Sezione
=======

Sottosezione
------------

Il formato reST gestisce molte altre cose (tabelle, note a piè di pagina, collegamenti ipertestuali etc..); per una descrizione dettagliata consultate la documentazione sul suo sito.

Le docutils

I documenti reST possono essere tradotti in vari formati grazie alle docutils. Inoltre, usando Sphinx, è possibile creare della documentazione per i propri software nel classico stile Python (ad esempio, vedi http://docs.python.org/).

Vediamo un esempio di utilizzo delle docutils. Innanzitutto creiamo un semplice file reST, pippo.rst, il cui contenuto è il seguente:

reStructuredText experiments
============================

Il *corsivo* è conosciuto nel resto del mondo come **italico**. Suona familiare?

Ora controlliamo se le docutils sono installate. Poiché si tratta di un modulo Python (con alcuni eseguibili di supporto) è possibile usare pip.

$ pip freeze | grep docutils

Qualora non fossero già presenti, è possibile installare le docutils sempre mediante pip, magari in un virtualenv apposito.

$ pip install docutils

Questo metodo è generale, ciascuna distribuzione Linux o qualsivoglia sistema operativo avrà sicuramente un modo per installarle mediante il proprio sistema di gestione dei pacchetti (ad esempio con la mia Arch potrei anche fare pacman -S docutils).

Una volta installate le docutils possiamo sbizzarrirci: convertiamo il nostro file reST in HTML, ODT e LaTeX:

$ rst2html.py pippo.rst > pippo.html

$ rst2odt.py pippo.rst > pippo.odt

$ rst2latex.py pippo.rst > pippo.tex

Per ottenere un PDF basterà compilare il file LaTeX:

$ pdflatex pippo.tex

Esistono convertitori anche per altri formati, più o meno esotici; i loro comandi sono sempre nella forma rst2qualcosa.py.