1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
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
|
