1 .. include:: ../disclaimer-ita.rst
2
3 .. note:: Per leggere la documentazione originale in inglese:
4 :ref:`Documentation/doc-guide/index.rst <doc_guide>`
5
6 .. _it_sphinxdoc:
7
8 =============================================
9 Usare Sphinx per la documentazione del kernel
10 =============================================
11
12 Il kernel Linux usa `Sphinx`_ per la generazione della documentazione a partire
13 dai file `reStructuredText`_ che si trovano nella cartella ``Documentation``.
14 Per generare la documentazione in HTML o PDF, usate comandi ``make htmldocs`` o
15 ``make pdfdocs``. La documentazione così generata sarà disponibile nella
16 cartella ``Documentation/output``.
17
18 .. _Sphinx: http://www.sphinx-doc.org/
19 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
20
21 I file reStructuredText possono contenere delle direttive che permettono di
22 includere i commenti di documentazione, o di tipo kernel-doc, dai file
23 sorgenti.
24 Solitamente questi commenti sono utilizzati per descrivere le funzioni, i tipi
25 e l'architettura del codice. I commenti di tipo kernel-doc hanno una struttura
26 e formato speciale, ma a parte questo vengono processati come reStructuredText.
27
28 Inoltre, ci sono migliaia di altri documenti in formato testo sparsi nella
29 cartella ``Documentation``. Alcuni di questi verranno probabilmente convertiti,
30 nel tempo, in formato reStructuredText, ma la maggior parte di questi rimarranno
31 in formato testo.
32
33 .. _it_sphinx_install:
34
35 Installazione Sphinx
36 ====================
37
38 I marcatori ReST utilizzati nei file in Documentation/ sono pensati per essere
39 processati da ``Sphinx`` nella versione 1.7 o superiore.
40
41 Esiste uno script che verifica i requisiti Sphinx. Per ulteriori dettagli
42 consultate :ref:`it_sphinx-pre-install`.
43
44 La maggior parte delle distribuzioni Linux forniscono Sphinx, ma l'insieme dei
45 programmi e librerie è fragile e non è raro che dopo un aggiornamento di
46 Sphinx, o qualche altro pacchetto Python, la documentazione non venga più
47 generata correttamente.
48
49 Un modo per evitare questo genere di problemi è quello di utilizzare una
50 versione diversa da quella fornita dalla vostra distribuzione. Per fare questo,
51 vi raccomandiamo di installare Sphinx dentro ad un ambiente virtuale usando
52 ``virtualenv-3`` o ``virtualenv`` a seconda di come Python 3 è stato
53 pacchettizzato dalla vostra distribuzione.
54
55 .. note::
56
57 #) Viene raccomandato l'uso del tema RTD per la documentazione in HTML.
58 A seconda della versione di Sphinx, potrebbe essere necessaria
59 l'installazione tramite il comando ``pip install sphinx_rtd_theme``.
60
61 #) Alcune pagine ReST contengono delle formule matematiche. A causa del
62 modo in cui Sphinx funziona, queste espressioni sono scritte
63 utilizzando LaTeX. Per una corretta interpretazione, è necessario aver
64 installato texlive con i pacchetti amdfonts e amsmath.
65
66 Riassumendo, se volete installare la versione 2.4.4 di Sphinx dovete eseguire::
67
68 $ virtualenv sphinx_2.4.4
69 $ . sphinx_2.4.4/bin/activate
70 (sphinx_2.4.4) $ pip install -r Documentation/sphinx/requirements.txt
71
72 Dopo aver eseguito ``. sphinx_2.4.4/bin/activate``, il prompt cambierà per
73 indicare che state usando il nuovo ambiente. Se aprite un nuova sessione,
74 prima di generare la documentazione, dovrete rieseguire questo comando per
75 rientrare nell'ambiente virtuale.
76
77 Generazione d'immagini
78 ----------------------
79
80 Il meccanismo che genera la documentazione del kernel contiene un'estensione
81 capace di gestire immagini in formato Graphviz e SVG (per maggior informazioni
82 vedere :ref:`it_sphinx_kfigure`).
83
84 Per far si che questo funzioni, dovete installare entrambe i pacchetti
85 Graphviz e ImageMagick. Il sistema di generazione della documentazione è in
86 grado di procedere anche se questi pacchetti non sono installati, ma il
87 risultato, ovviamente, non includerà le immagini.
88
89 Generazione in PDF e LaTeX
90 --------------------------
91
92 Al momento, la generazione di questi documenti è supportata solo dalle
93 versioni di Sphinx superiori alla 2.4.
94
95 Per la generazione di PDF e LaTeX, avrete bisogno anche del pacchetto
96 ``XeLaTeX`` nella versione 3.14159265
97
98 Per alcune distribuzioni Linux potrebbe essere necessario installare
99 anche una serie di pacchetti ``texlive`` in modo da fornire il supporto
100 minimo per il funzionamento di ``XeLaTeX``.
101
102 .. _it_sphinx-pre-install:
103
104 Verificare le dipendenze Sphinx
105 -------------------------------
106
107 Esiste uno script che permette di verificare automaticamente le dipendenze di
108 Sphinx. Se lo script riesce a riconoscere la vostra distribuzione, allora
109 sarà in grado di darvi dei suggerimenti su come procedere per completare
110 l'installazione::
111
112 $ ./scripts/sphinx-pre-install
113 Checking if the needed tools for Fedora release 26 (Twenty Six) are available
114 Warning: better to also install "texlive-luatex85".
115 You should run:
116
117 sudo dnf install -y texlive-luatex85
118 /usr/bin/virtualenv sphinx_2.4.4
119 . sphinx_2.4.4/bin/activate
120 pip install -r Documentation/sphinx/requirements.txt
121
122 Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.
123
124 L'impostazione predefinita prevede il controllo dei requisiti per la generazione
125 di documenti html e PDF, includendo anche il supporto per le immagini, le
126 espressioni matematiche e LaTeX; inoltre, presume che venga utilizzato un
127 ambiente virtuale per Python. I requisiti per generare i documenti html
128 sono considerati obbligatori, gli altri sono opzionali.
129
130 Questo script ha i seguenti parametri:
131
132 ``--no-pdf``
133 Disabilita i controlli per la generazione di PDF;
134
135 ``--no-virtualenv``
136 Utilizza l'ambiente predefinito dal sistema operativo invece che
137 l'ambiente virtuale per Python;
138
139
140 Generazione della documentazione Sphinx
141 =======================================
142
143 Per generare la documentazione in formato HTML o PDF si eseguono i rispettivi
144 comandi ``make htmldocs`` o ``make pdfdocs``. Esistono anche altri formati
145 in cui è possibile generare la documentazione; per maggiori informazioni
146 potere eseguire il comando ``make help``.
147 La documentazione così generata sarà disponibile nella sottocartella
148 ``Documentation/output``.
149
150 Ovviamente, per generare la documentazione, Sphinx (``sphinx-build``)
151 dev'essere installato. Se disponibile, il tema *Read the Docs* per Sphinx
152 verrà utilizzato per ottenere una documentazione HTML più gradevole.
153 Per la documentazione in formato PDF, invece, avrete bisogno di ``XeLaTeX`
154 e di ``convert(1)`` disponibile in ImageMagick
155 (https://www.imagemagick.org). \ [#ink]_
156 Tipicamente, tutti questi pacchetti sono disponibili e pacchettizzati nelle
157 distribuzioni Linux.
158
159 Per poter passare ulteriori opzioni a Sphinx potete utilizzare la variabile
160 make ``SPHINXOPTS``. Per esempio, se volete che Sphinx sia più verboso durante
161 la generazione potete usare il seguente comando ``make SPHINXOPTS=-v htmldocs``.
162
163 Potete anche personalizzare l'ouptut html passando un livello aggiuntivo
164 DOCS_CSS usando la rispettiva variabile d'ambiente ``DOCS_CSS``.
165
166 La variable make ``SPHINXDIRS`` è utile quando si vuole generare solo una parte
167 della documentazione. Per esempio, si possono generare solo di documenti in
168 ``Documentation/doc-guide`` eseguendo ``make SPHINXDIRS=doc-guide htmldocs``. La
169 sezione dedicata alla documentazione di ``make help`` vi mostrerà quali sotto
170 cartelle potete specificare.
171
172 Potete eliminare la documentazione generata tramite il comando
173 ``make cleandocs``.
174
175 .. [#ink] Avere installato anche ``inkscape(1)`` dal progetto Inkscape ()
176 potrebbe aumentare la qualità delle immagini che verranno integrate
177 nel documento PDF, specialmente per quando si usando rilasci del
178 kernel uguali o superiori a 5.18
179
180 Scrivere la documentazione
181 ==========================
182
183 Aggiungere nuova documentazione è semplice:
184
185 1. aggiungete un file ``.rst`` nella sottocartella ``Documentation``
186 2. aggiungete un riferimento ad esso nell'indice (`TOC tree`_) in
187 ``Documentation/index.rst``.
188
189 .. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html
190
191 Questo, di solito, è sufficiente per la documentazione più semplice (come
192 quella che state leggendo ora), ma per una documentazione più elaborata è
193 consigliato creare una sottocartella dedicata (o, quando possibile, utilizzarne
194 una già esistente). Per esempio, il sottosistema grafico è documentato nella
195 sottocartella ``Documentation/gpu``; questa documentazione è divisa in
196 diversi file ``.rst`` ed un indice ``index.rst`` (con un ``toctree``
197 dedicato) a cui si fa riferimento nell'indice principale.
198
199 Consultate la documentazione di `Sphinx`_ e `reStructuredText`_ per maggiori
200 informazione circa le loro potenzialità. In particolare, il
201 `manuale introduttivo a reStructuredText`_ di Sphinx è un buon punto da
202 cui cominciare. Esistono, inoltre, anche alcuni
203 `costruttori specifici per Sphinx`_.
204
205 .. _`manuale introduttivo a reStructuredText`: http://www.sphinx-doc.org/en/stable/rest.html
206 .. _`costruttori specifici per Sphinx`: http://www.sphinx-doc.org/en/stable/markup/index.html
207
208 Guide linea per la documentazione del kernel
209 --------------------------------------------
210
211 In questa sezione troverete alcune linee guida specifiche per la documentazione
212 del kernel:
213
214 * Non esagerate con i costrutti di reStructuredText. Mantenete la
215 documentazione semplice. La maggior parte della documentazione dovrebbe
216 essere testo semplice con una strutturazione minima che permetta la
217 conversione in diversi formati.
218
219 * Mantenete la strutturazione il più fedele possibile all'originale quando
220 convertite un documento in formato reStructuredText.
221
222 * Aggiornate i contenuti quando convertite della documentazione, non limitatevi
223 solo alla formattazione.
224
225 * Mantenete la decorazione dei livelli di intestazione come segue:
226
227 1. ``=`` con una linea superiore per il titolo del documento::
228
229 ======
230 Titolo
231 ======
232
233 2. ``=`` per i capitoli::
234
235 Capitoli
236 ========
237
238 3. ``-`` per le sezioni::
239
240 Sezioni
241 -------
242
243 4. ``~`` per le sottosezioni::
244
245 Sottosezioni
246 ~~~~~~~~~~~~
247
248 Sebbene RST non forzi alcun ordine specifico (*Piuttosto che imporre
249 un numero ed un ordine fisso di decorazioni, l'ordine utilizzato sarà
250 quello incontrato*), avere uniformità dei livelli principali rende più
251 semplice la lettura dei documenti.
252
253 * Per inserire blocchi di testo con caratteri a dimensione fissa (codici di
254 esempio, casi d'uso, eccetera): utilizzate ``::`` quando non è necessario
255 evidenziare la sintassi, specialmente per piccoli frammenti; invece,
256 utilizzate ``.. code-block:: <language>`` per blocchi più lunghi che
257 beneficeranno della sintassi evidenziata. Per un breve pezzo di codice da
258 inserire nel testo, usate \`\`.
259
260
261 Il dominio C
262 ------------
263
264 Il **Dominio Sphinx C** (denominato c) è adatto alla documentazione delle API C.
265 Per esempio, un prototipo di una funzione:
266
267 .. code-block:: rst
268
269 .. c:function:: int ioctl( int fd, int request )
270
271 Il dominio C per kernel-doc ha delle funzionalità aggiuntive. Per esempio,
272 potete assegnare un nuovo nome di riferimento ad una funzione con un nome
273 molto comune come ``open`` o ``ioctl``:
274
275 .. code-block:: rst
276
277 .. c:function:: int ioctl( int fd, int request )
278 :name: VIDIOC_LOG_STATUS
279
280 Il nome della funzione (per esempio ioctl) rimane nel testo ma il nome del suo
281 riferimento cambia da ``ioctl`` a ``VIDIOC_LOG_STATUS``. Anche la voce
282 nell'indice cambia in ``VIDIOC_LOG_STATUS``.
283
284 Notate che per una funzione non c'è bisogno di usare ``c:func:`` per generarne
285 i riferimenti nella documentazione. Grazie a qualche magica estensione a
286 Sphinx, il sistema di generazione della documentazione trasformerà
287 automaticamente un riferimento ad una ``funzione()`` in un riferimento
288 incrociato quando questa ha una voce nell'indice. Se trovate degli usi di
289 ``c:func:`` nella documentazione del kernel, sentitevi liberi di rimuoverli.
290
291
292 Tabelle a liste
293 ---------------
294
295 Il formato ``list-table`` può essere utile per tutte quelle tabelle che non
296 possono essere facilmente scritte usando il formato ASCII-art di Sphinx. Però,
297 questo genere di tabelle sono illeggibili per chi legge direttamente i file di
298 testo. Dunque, questo formato dovrebbe essere evitato senza forti argomenti che
299 ne giustifichino l'uso.
300
301 La ``flat-table`` è anch'essa una lista di liste simile alle ``list-table``
302 ma con delle funzionalità aggiuntive:
303
304 * column-span: col ruolo ``cspan`` una cella può essere estesa attraverso
305 colonne successive
306
307 * raw-span: col ruolo ``rspan`` una cella può essere estesa attraverso
308 righe successive
309
310 * auto-span: la cella più a destra viene estesa verso destra per compensare
311 la mancanza di celle. Con l'opzione ``:fill-cells:`` questo comportamento
312 può essere cambiato da *auto-span* ad *auto-fill*, il quale inserisce
313 automaticamente celle (vuote) invece che estendere l'ultima.
314
315 opzioni:
316
317 * ``:header-rows:`` [int] conta le righe di intestazione
318 * ``:stub-columns:`` [int] conta le colonne di stub
319 * ``:widths:`` [[int] [int] ... ] larghezza delle colonne
320 * ``:fill-cells:`` invece di estendere automaticamente una cella su quelle
321 mancanti, ne crea di vuote.
322
323 ruoli:
324
325 * ``:cspan:`` [int] colonne successive (*morecols*)
326 * ``:rspan:`` [int] righe successive (*morerows*)
327
328 L'esempio successivo mostra come usare questo marcatore. Il primo livello della
329 nostra lista di liste è la *riga*. In una *riga* è possibile inserire solamente
330 la lista di celle che compongono la *riga* stessa. Fanno eccezione i *commenti*
331 ( ``..`` ) ed i *collegamenti* (per esempio, un riferimento a
332 ``:ref:`last row <last row>``` / :ref:`last row <it last row>`)
333
334 .. code-block:: rst
335
336 .. flat-table:: table title
337 :widths: 2 1 1 3
338
339 * - head col 1
340 - head col 2
341 - head col 3
342 - head col 4
343
344 * - row 1
345 - field 1.1
346 - field 1.2 with autospan
347
348 * - row 2
349 - field 2.1
350 - :rspan:`1` :cspan:`1` field 2.2 - 3.3
351
352 * .. _`it last row`:
353
354 - row 3
355
356 Che verrà rappresentata nel seguente modo:
357
358 .. flat-table:: table title
359 :widths: 2 1 1 3
360
361 * - head col 1
362 - head col 2
363 - head col 3
364 - head col 4
365
366 * - row 1
367 - field 1.1
368 - field 1.2 with autospan
369
370 * - row 2
371 - field 2.1
372 - :rspan:`1` :cspan:`1` field 2.2 - 3.3
373
374 * .. _`it last row`:
375
376 - row 3
377
378 Riferimenti incrociati
379 ----------------------
380
381 Aggiungere un riferimento incrociato da una pagina della
382 documentazione ad un'altra può essere fatto scrivendo il percorso al
383 file corrispondende, non serve alcuna sintassi speciale. Si possono
384 usare sia percorsi assoluti che relativi. Quelli assoluti iniziano con
385 "documentation/". Per esempio, potete fare riferimento a questo
386 documento in uno dei seguenti modi (da notare che l'estensione
387 ``.rst`` è necessaria)::
388
389 Vedere Documentation/doc-guide/sphinx.rst. Questo funziona sempre
390 Guardate pshinx.rst, che si trova nella stessa cartella.
391 Leggete ../sphinx.rst, che si trova nella cartella precedente.
392
393 Se volete che il collegamento abbia un testo diverso rispetto al
394 titolo del documento, allora dovrete usare la direttiva Sphinx
395 ``doc``. Per esempio::
396
397 Vedere :doc:`il mio testo per il collegamento <sphinx>`.
398
399 Nella maggioranza dei casi si consiglia il primo metodo perché è più
400 pulito ed adatto a chi legge dai sorgenti. Se incontrare un ``:doc:``
401 che non da alcun valore, sentitevi liberi di convertirlo in un
402 percorso al documento.
403
404 Per informazioni riguardo ai riferimenti incrociati ai commenti
405 kernel-doc per funzioni o tipi, consultate
406
407 .. _it_sphinx_kfigure:
408
409 Figure ed immagini
410 ==================
411
412 Se volete aggiungere un'immagine, utilizzate le direttive ``kernel-figure``
413 e ``kernel-image``. Per esempio, per inserire una figura di un'immagine in
414 formato SVG (:ref:`it_svg_image_example`)::
415
416 .. kernel-figure:: ../../../doc-guide/svg_image.svg
417 :alt: una semplice immagine SVG
418
419 Una semplice immagine SVG
420
421 .. _it_svg_image_example:
422
423 .. kernel-figure:: ../../../doc-guide/svg_image.svg
424 :alt: una semplice immagine SVG
425
426 Una semplice immagine SVG
427
428 Le direttive del kernel per figure ed immagini supportano il formato **DOT**,
429 per maggiori informazioni
430
431 * DOT: http://graphviz.org/pdf/dotguide.pdf
432 * Graphviz: http://www.graphviz.org/content/dot-language
433
434 Un piccolo esempio (:ref:`it_hello_dot_file`)::
435
436 .. kernel-figure:: ../../../doc-guide/hello.dot
437 :alt: ciao mondo
438
439 Esempio DOT
440
441 .. _it_hello_dot_file:
442
443 .. kernel-figure:: ../../../doc-guide/hello.dot
444 :alt: ciao mondo
445
446 Esempio DOT
447
448 Tramite la direttiva ``kernel-render`` è possibile aggiungere codice specifico;
449 ad esempio nel formato **DOT** di Graphviz.::
450
451 .. kernel-render:: DOT
452 :alt: foobar digraph
453 :caption: Codice **DOT** (Graphviz) integrato
454
455 digraph foo {
456 "bar" -> "baz";
457 }
458
459 La rappresentazione dipenderà dei programmi installati. Se avete Graphviz
460 installato, vedrete un'immagine vettoriale. In caso contrario, il codice grezzo
461 verrà rappresentato come *blocco testuale* (:ref:`it_hello_dot_render`).
462
463 .. _it_hello_dot_render:
464
465 .. kernel-render:: DOT
466 :alt: foobar digraph
467 :caption: Codice **DOT** (Graphviz) integrato
468
469 digraph foo {
470 "bar" -> "baz";
471 }
472
473 La direttiva *render* ha tutte le opzioni della direttiva *figure*, con
474 l'aggiunta dell'opzione ``caption``. Se ``caption`` ha un valore allora
475 un nodo *figure* viene aggiunto. Altrimenti verrà aggiunto un nodo *image*.
476 L'opzione ``caption`` è necessaria in caso si vogliano aggiungere dei
477 riferimenti (:ref:`it_hello_svg_render`).
478
479 Per la scrittura di codice **SVG**::
480
481 .. kernel-render:: SVG
482 :caption: Integrare codice **SVG**
483 :alt: so-nw-arrow
484
485 <?xml version="1.0" encoding="UTF-8"?>
486 <svg xmlns="http://www.w3.org/2000/svg" version="1.1" ...>
487 ...
488 </svg>
489
490 .. _it_hello_svg_render:
491
492 .. kernel-render:: SVG
493 :caption: Integrare codice **SVG**
494 :alt: so-nw-arrow
495
496 <?xml version="1.0" encoding="UTF-8"?>
497 <svg xmlns="http://www.w3.org/2000/svg"
498 version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400">
499 <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>
500 <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>
501 </svg>
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.