Docutils è una suite per la gestione di documentazione scritta in python; è interamente basata sull'uso di reStructuredText come formato sorgente e ne comprende le specifiche.
Comprende i moduli python usati dalla maggior parte dei programmi che gestiscono reStructuredText, ma anche alcuni script usabili per effettuare rapide conversioni da riga di comando.
Per convertire rapidamente un documento reStructuredText in <formato> si usa:
rst2<formato> [opzioni] [documento [destinazione]]
ad esempio:
rst2html documento.rst documento.html
L'elenco di opzioni disponibili si ottiene con:
rst2<formato> --help
e sono documentate in dettaglio nella configurazione di docutils.
Un semplice esempio di uso dei moduli docutils all'interno di programmi in python è presente nello script build.py usato per generare questa documentazione; l'equivalente della semplice conversione usata sopra si ottiene con:
from docutils.core import publish_file publish_file(source_path=<documento>, destination_path=<destinazione>, writer_name=<formato>)
ad esempio:
from docutils.core import publish_file publish_file(source_path='documento.rst', destination_path='documento.html', writer_name='html')
Ulteriori dettagli sono ovviamente presenti nella documentazione di docutils
Docutils può ovviamente generare HTML tramite il writer html, usato dal comando rst2html. È possibile anche generare delle presentazioni compatibili con S5, un sistema di slideshow in HTML5 e JavaScript; per farlo si usa il comando rst2s5 o il writer s5_html, ad esempio:
rst2s5 --theme medium-black documento.rst documento.html
Il sito di docutils comprende ulteriore documentazione sugli strumenti per generare html.
La generazione di documenti in PDF (ma ovviamente anche PostScript e dvi) è delegata a LaTeX a partire da un .tex ottenuto dal writer latex (o dal comando rst2latex). Meglio ancora, specialmente nel caso si usino caratteri di lingue diverse e si voglia ottenere un documento PDF, è usare xeTeX, assieme al writer xetex o al comando rst2xetex; ad esempio:
rst2xetex documento.rst documento.tex xelatex documento.tex && xelatex documento.tex && xelatex documento.tex
(dove il comando xelatex è ripetuto tre volte per essere sicuri che tutti i riferimenti interdocumento siano corretti).
Un problema nel quale si può incappare è che xeTeX non supporta l'inserimento di immagini in svg; per inserire immagini vettoriali è necessario usare PDF.
Sul sito docutils c'è un documento su come generare LaTeX con docutils.
Docutils comprende un writer odt e relativo programma rst2odt con i quali generare file odt a partire da reStructuredText. I risultati non sono ovviamente piacevoli quanto i file generati tramite LaTeX, ma possono essere utili in determinati casi.
Al fine di completare la documentazione di un programma con una pagina di man, docutils include un writer manpage e il relativo programma rst2man, che trasformano un documento reStructuredText che soddisfa determinate convenzioni in una pagina in *roff visualizzabile con man.
Sul sito docutils si trova della documentazione alle voci manpage e rst2man.