Docutils
--------

.. contents::

Docutils_ è una suite per la gestione di documentazione scritta 
in python; è interamente basata sull'uso di |reST| come formato 
sorgente e ne comprende le specifiche.

Comprende i moduli python usati dalla maggior parte dei programmi 
che gestiscono |reST|, ma anche alcuni script usabili per 
effettuare rapide conversioni da riga di comando.

.. _Docutils: http://docutils.sourceforge.net/index.html

.. |reST| replace:: reStructuredText

Uso
^^^

Per convertire rapidamente un documento |reST| 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`_.

.. _`configurazione di docutils`: http://docutils.sourceforge.net/docs/user/config.html

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`_

.. _`documentazione di docutils`: http://docutils.sourceforge.net/docs/index.html

Formati generabili
^^^^^^^^^^^^^^^^^^

HTML
~~~~

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`_, compresa una `guida su s5`_.

.. _S5: http://meyerweb.com/eric/tools/s5/
.. _presentazioni: http://docutils.sourceforge.net/docs/user/slide-shows.html
.. _`strumenti per generare html`: http://docutils.sourceforge.net/docs/user/tools.html#html-generating-tools
.. _`guida su s5`: http://docutils.sourceforge.net/docs/user/slide-shows.html

PDF
~~~

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`_.
   
.. _`generare LaTeX con docutils`: http://docutils.sourceforge.net/docs/user/latex.html

ODT
~~~

Docutils comprende un writer ``odt`` e relativo programma ``rst2odt`` 
con i quali `generare file odt`_ a partire da |reST|.
I risultati non sono ovviamente piacevoli quanto i file generati 
tramite LaTeX, ma possono essere utili in determinati casi.

.. _`generare file odt`: http://docutils.sourceforge.net/docs/user/odt.html

manpages
~~~~~~~~

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 |reST| che soddisfa determinate convenzioni in 
una pagina in \*roff visualizzabile con ``man``.

Sul sito docutils si trova della documentazione alle voci 
manpage_ e rst2man_.

.. _manpage: http://docutils.sourceforge.net/docs/user/manpage.html
.. _rst2man: http://docutils.sourceforge.net/sandbox/manpage-writer/rst2man.txt