diff options
| -rw-r--r-- | strumenti/docutils.rst | 130 |
1 files changed, 130 insertions, 0 deletions
diff --git a/strumenti/docutils.rst b/strumenti/docutils.rst new file mode 100644 index 0000000..4e250b6 --- /dev/null +++ b/strumenti/docutils.rst @@ -0,0 +1,130 @@ +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`_. + +.. _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 + +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 + |