0001 .. include:: ../disclaimer-ita.rst
0002
0003 .. note:: Per leggere la documentazione originale in inglese:
0004 :ref:`Documentation/doc-guide/index.rst <doc_guide>`
0005
0006 .. _it_sphinxdoc:
0007
0008 =============================================
0009 Usare Sphinx per la documentazione del kernel
0010 =============================================
0011
0012 Il kernel Linux usa `Sphinx`_ per la generazione della documentazione a partire
0013 dai file `reStructuredText`_ che si trovano nella cartella ``Documentation``.
0014 Per generare la documentazione in HTML o PDF, usate comandi ``make htmldocs`` o
0015 ``make pdfdocs``. La documentazione così generata sarà disponibile nella
0016 cartella ``Documentation/output``.
0017
0018 .. _Sphinx: http://www.sphinx-doc.org/
0019 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
0020
0021 I file reStructuredText possono contenere delle direttive che permettono di
0022 includere i commenti di documentazione, o di tipo kernel-doc, dai file
0023 sorgenti.
0024 Solitamente questi commenti sono utilizzati per descrivere le funzioni, i tipi
0025 e l'architettura del codice. I commenti di tipo kernel-doc hanno una struttura
0026 e formato speciale, ma a parte questo vengono processati come reStructuredText.
0027
0028 Inoltre, ci sono migliaia di altri documenti in formato testo sparsi nella
0029 cartella ``Documentation``. Alcuni di questi verranno probabilmente convertiti,
0030 nel tempo, in formato reStructuredText, ma la maggior parte di questi rimarranno
0031 in formato testo.
0032
0033 .. _it_sphinx_install:
0034
0035 Installazione Sphinx
0036 ====================
0037
0038 I marcatori ReST utilizzati nei file in Documentation/ sono pensati per essere
0039 processati da ``Sphinx`` nella versione 1.7 o superiore.
0040
0041 Esiste uno script che verifica i requisiti Sphinx. Per ulteriori dettagli
0042 consultate :ref:`it_sphinx-pre-install`.
0043
0044 La maggior parte delle distribuzioni Linux forniscono Sphinx, ma l'insieme dei
0045 programmi e librerie è fragile e non è raro che dopo un aggiornamento di
0046 Sphinx, o qualche altro pacchetto Python, la documentazione non venga più
0047 generata correttamente.
0048
0049 Un modo per evitare questo genere di problemi è quello di utilizzare una
0050 versione diversa da quella fornita dalla vostra distribuzione. Per fare questo,
0051 vi raccomandiamo di installare Sphinx dentro ad un ambiente virtuale usando
0052 ``virtualenv-3`` o ``virtualenv`` a seconda di come Python 3 è stato
0053 pacchettizzato dalla vostra distribuzione.
0054
0055 .. note::
0056
0057 #) Viene raccomandato l'uso del tema RTD per la documentazione in HTML.
0058 A seconda della versione di Sphinx, potrebbe essere necessaria
0059 l'installazione tramite il comando ``pip install sphinx_rtd_theme``.
0060
0061 #) Alcune pagine ReST contengono delle formule matematiche. A causa del
0062 modo in cui Sphinx funziona, queste espressioni sono scritte
0063 utilizzando LaTeX. Per una corretta interpretazione, è necessario aver
0064 installato texlive con i pacchetti amdfonts e amsmath.
0065
0066 Riassumendo, se volete installare la versione 2.4.4 di Sphinx dovete eseguire::
0067
0068 $ virtualenv sphinx_2.4.4
0069 $ . sphinx_2.4.4/bin/activate
0070 (sphinx_2.4.4) $ pip install -r Documentation/sphinx/requirements.txt
0071
0072 Dopo aver eseguito ``. sphinx_2.4.4/bin/activate``, il prompt cambierà per
0073 indicare che state usando il nuovo ambiente. Se aprite un nuova sessione,
0074 prima di generare la documentazione, dovrete rieseguire questo comando per
0075 rientrare nell'ambiente virtuale.
0076
0077 Generazione d'immagini
0078 ----------------------
0079
0080 Il meccanismo che genera la documentazione del kernel contiene un'estensione
0081 capace di gestire immagini in formato Graphviz e SVG (per maggior informazioni
0082 vedere :ref:`it_sphinx_kfigure`).
0083
0084 Per far si che questo funzioni, dovete installare entrambe i pacchetti
0085 Graphviz e ImageMagick. Il sistema di generazione della documentazione è in
0086 grado di procedere anche se questi pacchetti non sono installati, ma il
0087 risultato, ovviamente, non includerà le immagini.
0088
0089 Generazione in PDF e LaTeX
0090 --------------------------
0091
0092 Al momento, la generazione di questi documenti è supportata solo dalle
0093 versioni di Sphinx superiori alla 2.4.
0094
0095 Per la generazione di PDF e LaTeX, avrete bisogno anche del pacchetto
0096 ``XeLaTeX`` nella versione 3.14159265
0097
0098 Per alcune distribuzioni Linux potrebbe essere necessario installare
0099 anche una serie di pacchetti ``texlive`` in modo da fornire il supporto
0100 minimo per il funzionamento di ``XeLaTeX``.
0101
0102 .. _it_sphinx-pre-install:
0103
0104 Verificare le dipendenze Sphinx
0105 -------------------------------
0106
0107 Esiste uno script che permette di verificare automaticamente le dipendenze di
0108 Sphinx. Se lo script riesce a riconoscere la vostra distribuzione, allora
0109 sarà in grado di darvi dei suggerimenti su come procedere per completare
0110 l'installazione::
0111
0112 $ ./scripts/sphinx-pre-install
0113 Checking if the needed tools for Fedora release 26 (Twenty Six) are available
0114 Warning: better to also install "texlive-luatex85".
0115 You should run:
0116
0117 sudo dnf install -y texlive-luatex85
0118 /usr/bin/virtualenv sphinx_2.4.4
0119 . sphinx_2.4.4/bin/activate
0120 pip install -r Documentation/sphinx/requirements.txt
0121
0122 Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.
0123
0124 L'impostazione predefinita prevede il controllo dei requisiti per la generazione
0125 di documenti html e PDF, includendo anche il supporto per le immagini, le
0126 espressioni matematiche e LaTeX; inoltre, presume che venga utilizzato un
0127 ambiente virtuale per Python. I requisiti per generare i documenti html
0128 sono considerati obbligatori, gli altri sono opzionali.
0129
0130 Questo script ha i seguenti parametri:
0131
0132 ``--no-pdf``
0133 Disabilita i controlli per la generazione di PDF;
0134
0135 ``--no-virtualenv``
0136 Utilizza l'ambiente predefinito dal sistema operativo invece che
0137 l'ambiente virtuale per Python;
0138
0139
0140 Generazione della documentazione Sphinx
0141 =======================================
0142
0143 Per generare la documentazione in formato HTML o PDF si eseguono i rispettivi
0144 comandi ``make htmldocs`` o ``make pdfdocs``. Esistono anche altri formati
0145 in cui è possibile generare la documentazione; per maggiori informazioni
0146 potere eseguire il comando ``make help``.
0147 La documentazione così generata sarà disponibile nella sottocartella
0148 ``Documentation/output``.
0149
0150 Ovviamente, per generare la documentazione, Sphinx (``sphinx-build``)
0151 dev'essere installato. Se disponibile, il tema *Read the Docs* per Sphinx
0152 verrà utilizzato per ottenere una documentazione HTML più gradevole.
0153 Per la documentazione in formato PDF, invece, avrete bisogno di ``XeLaTeX`
0154 e di ``convert(1)`` disponibile in ImageMagick (https://www.imagemagick.org).
0155 Tipicamente, tutti questi pacchetti sono disponibili e pacchettizzati nelle
0156 distribuzioni Linux.
0157
0158 Per poter passare ulteriori opzioni a Sphinx potete utilizzare la variabile
0159 make ``SPHINXOPTS``. Per esempio, se volete che Sphinx sia più verboso durante
0160 la generazione potete usare il seguente comando ``make SPHINXOPTS=-v htmldocs``.
0161
0162 Potete anche personalizzare l'ouptut html passando un livello aggiuntivo
0163 DOCS_CSS usando la rispettiva variabile d'ambiente ``DOCS_CSS``.
0164
0165 Potete eliminare la documentazione generata tramite il comando
0166 ``make cleandocs``.
0167
0168 Scrivere la documentazione
0169 ==========================
0170
0171 Aggiungere nuova documentazione è semplice:
0172
0173 1. aggiungete un file ``.rst`` nella sottocartella ``Documentation``
0174 2. aggiungete un riferimento ad esso nell'indice (`TOC tree`_) in
0175 ``Documentation/index.rst``.
0176
0177 .. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html
0178
0179 Questo, di solito, è sufficiente per la documentazione più semplice (come
0180 quella che state leggendo ora), ma per una documentazione più elaborata è
0181 consigliato creare una sottocartella dedicata (o, quando possibile, utilizzarne
0182 una già esistente). Per esempio, il sottosistema grafico è documentato nella
0183 sottocartella ``Documentation/gpu``; questa documentazione è divisa in
0184 diversi file ``.rst`` ed un indice ``index.rst`` (con un ``toctree``
0185 dedicato) a cui si fa riferimento nell'indice principale.
0186
0187 Consultate la documentazione di `Sphinx`_ e `reStructuredText`_ per maggiori
0188 informazione circa le loro potenzialità. In particolare, il
0189 `manuale introduttivo a reStructuredText`_ di Sphinx è un buon punto da
0190 cui cominciare. Esistono, inoltre, anche alcuni
0191 `costruttori specifici per Sphinx`_.
0192
0193 .. _`manuale introduttivo a reStructuredText`: http://www.sphinx-doc.org/en/stable/rest.html
0194 .. _`costruttori specifici per Sphinx`: http://www.sphinx-doc.org/en/stable/markup/index.html
0195
0196 Guide linea per la documentazione del kernel
0197 --------------------------------------------
0198
0199 In questa sezione troverete alcune linee guida specifiche per la documentazione
0200 del kernel:
0201
0202 * Non esagerate con i costrutti di reStructuredText. Mantenete la
0203 documentazione semplice. La maggior parte della documentazione dovrebbe
0204 essere testo semplice con una strutturazione minima che permetta la
0205 conversione in diversi formati.
0206
0207 * Mantenete la strutturazione il più fedele possibile all'originale quando
0208 convertite un documento in formato reStructuredText.
0209
0210 * Aggiornate i contenuti quando convertite della documentazione, non limitatevi
0211 solo alla formattazione.
0212
0213 * Mantenete la decorazione dei livelli di intestazione come segue:
0214
0215 1. ``=`` con una linea superiore per il titolo del documento::
0216
0217 ======
0218 Titolo
0219 ======
0220
0221 2. ``=`` per i capitoli::
0222
0223 Capitoli
0224 ========
0225
0226 3. ``-`` per le sezioni::
0227
0228 Sezioni
0229 -------
0230
0231 4. ``~`` per le sottosezioni::
0232
0233 Sottosezioni
0234 ~~~~~~~~~~~~
0235
0236 Sebbene RST non forzi alcun ordine specifico (*Piuttosto che imporre
0237 un numero ed un ordine fisso di decorazioni, l'ordine utilizzato sarà
0238 quello incontrato*), avere uniformità dei livelli principali rende più
0239 semplice la lettura dei documenti.
0240
0241 * Per inserire blocchi di testo con caratteri a dimensione fissa (codici di
0242 esempio, casi d'uso, eccetera): utilizzate ``::`` quando non è necessario
0243 evidenziare la sintassi, specialmente per piccoli frammenti; invece,
0244 utilizzate ``.. code-block:: <language>`` per blocchi più lunghi che
0245 beneficeranno della sintassi evidenziata. Per un breve pezzo di codice da
0246 inserire nel testo, usate \`\`.
0247
0248
0249 Il dominio C
0250 ------------
0251
0252 Il **Dominio Sphinx C** (denominato c) è adatto alla documentazione delle API C.
0253 Per esempio, un prototipo di una funzione:
0254
0255 .. code-block:: rst
0256
0257 .. c:function:: int ioctl( int fd, int request )
0258
0259 Il dominio C per kernel-doc ha delle funzionalità aggiuntive. Per esempio,
0260 potete assegnare un nuovo nome di riferimento ad una funzione con un nome
0261 molto comune come ``open`` o ``ioctl``:
0262
0263 .. code-block:: rst
0264
0265 .. c:function:: int ioctl( int fd, int request )
0266 :name: VIDIOC_LOG_STATUS
0267
0268 Il nome della funzione (per esempio ioctl) rimane nel testo ma il nome del suo
0269 riferimento cambia da ``ioctl`` a ``VIDIOC_LOG_STATUS``. Anche la voce
0270 nell'indice cambia in ``VIDIOC_LOG_STATUS``.
0271
0272 Notate che per una funzione non c'è bisogno di usare ``c:func:`` per generarne
0273 i riferimenti nella documentazione. Grazie a qualche magica estensione a
0274 Sphinx, il sistema di generazione della documentazione trasformerà
0275 automaticamente un riferimento ad una ``funzione()`` in un riferimento
0276 incrociato quando questa ha una voce nell'indice. Se trovate degli usi di
0277 ``c:func:`` nella documentazione del kernel, sentitevi liberi di rimuoverli.
0278
0279
0280 Tabelle a liste
0281 ---------------
0282
0283 Il formato ``list-table`` può essere utile per tutte quelle tabelle che non
0284 possono essere facilmente scritte usando il formato ASCII-art di Sphinx. Però,
0285 questo genere di tabelle sono illeggibili per chi legge direttamente i file di
0286 testo. Dunque, questo formato dovrebbe essere evitato senza forti argomenti che
0287 ne giustifichino l'uso.
0288
0289 La ``flat-table`` è anch'essa una lista di liste simile alle ``list-table``
0290 ma con delle funzionalità aggiuntive:
0291
0292 * column-span: col ruolo ``cspan`` una cella può essere estesa attraverso
0293 colonne successive
0294
0295 * raw-span: col ruolo ``rspan`` una cella può essere estesa attraverso
0296 righe successive
0297
0298 * auto-span: la cella più a destra viene estesa verso destra per compensare
0299 la mancanza di celle. Con l'opzione ``:fill-cells:`` questo comportamento
0300 può essere cambiato da *auto-span* ad *auto-fill*, il quale inserisce
0301 automaticamente celle (vuote) invece che estendere l'ultima.
0302
0303 opzioni:
0304
0305 * ``:header-rows:`` [int] conta le righe di intestazione
0306 * ``:stub-columns:`` [int] conta le colonne di stub
0307 * ``:widths:`` [[int] [int] ... ] larghezza delle colonne
0308 * ``:fill-cells:`` invece di estendere automaticamente una cella su quelle
0309 mancanti, ne crea di vuote.
0310
0311 ruoli:
0312
0313 * ``:cspan:`` [int] colonne successive (*morecols*)
0314 * ``:rspan:`` [int] righe successive (*morerows*)
0315
0316 L'esempio successivo mostra come usare questo marcatore. Il primo livello della
0317 nostra lista di liste è la *riga*. In una *riga* è possibile inserire solamente
0318 la lista di celle che compongono la *riga* stessa. Fanno eccezione i *commenti*
0319 ( ``..`` ) ed i *collegamenti* (per esempio, un riferimento a
0320 ``:ref:`last row <last row>``` / :ref:`last row <it last row>`)
0321
0322 .. code-block:: rst
0323
0324 .. flat-table:: table title
0325 :widths: 2 1 1 3
0326
0327 * - head col 1
0328 - head col 2
0329 - head col 3
0330 - head col 4
0331
0332 * - row 1
0333 - field 1.1
0334 - field 1.2 with autospan
0335
0336 * - row 2
0337 - field 2.1
0338 - :rspan:`1` :cspan:`1` field 2.2 - 3.3
0339
0340 * .. _`it last row`:
0341
0342 - row 3
0343
0344 Che verrà rappresentata nel seguente modo:
0345
0346 .. flat-table:: table title
0347 :widths: 2 1 1 3
0348
0349 * - head col 1
0350 - head col 2
0351 - head col 3
0352 - head col 4
0353
0354 * - row 1
0355 - field 1.1
0356 - field 1.2 with autospan
0357
0358 * - row 2
0359 - field 2.1
0360 - :rspan:`1` :cspan:`1` field 2.2 - 3.3
0361
0362 * .. _`it last row`:
0363
0364 - row 3
0365
0366 Riferimenti incrociati
0367 ----------------------
0368
0369 Aggiungere un riferimento incrociato da una pagina della
0370 documentazione ad un'altra può essere fatto scrivendo il percorso al
0371 file corrispondende, non serve alcuna sintassi speciale. Si possono
0372 usare sia percorsi assoluti che relativi. Quelli assoluti iniziano con
0373 "documentation/". Per esempio, potete fare riferimento a questo
0374 documento in uno dei seguenti modi (da notare che l'estensione
0375 ``.rst`` è necessaria)::
0376
0377 Vedere Documentation/doc-guide/sphinx.rst. Questo funziona sempre
0378 Guardate pshinx.rst, che si trova nella stessa cartella.
0379 Leggete ../sphinx.rst, che si trova nella cartella precedente.
0380
0381 Se volete che il collegamento abbia un testo diverso rispetto al
0382 titolo del documento, allora dovrete usare la direttiva Sphinx
0383 ``doc``. Per esempio::
0384
0385 Vedere :doc:`il mio testo per il collegamento <sphinx>`.
0386
0387 Nella maggioranza dei casi si consiglia il primo metodo perché è più
0388 pulito ed adatto a chi legge dai sorgenti. Se incontrare un ``:doc:``
0389 che non da alcun valore, sentitevi liberi di convertirlo in un
0390 percorso al documento.
0391
0392 Per informazioni riguardo ai riferimenti incrociati ai commenti
0393 kernel-doc per funzioni o tipi, consultate
0394
0395 .. _it_sphinx_kfigure:
0396
0397 Figure ed immagini
0398 ==================
0399
0400 Se volete aggiungere un'immagine, utilizzate le direttive ``kernel-figure``
0401 e ``kernel-image``. Per esempio, per inserire una figura di un'immagine in
0402 formato SVG (:ref:`it_svg_image_example`)::
0403
0404 .. kernel-figure:: ../../../doc-guide/svg_image.svg
0405 :alt: una semplice immagine SVG
0406
0407 Una semplice immagine SVG
0408
0409 .. _it_svg_image_example:
0410
0411 .. kernel-figure:: ../../../doc-guide/svg_image.svg
0412 :alt: una semplice immagine SVG
0413
0414 Una semplice immagine SVG
0415
0416 Le direttive del kernel per figure ed immagini supportano il formato **DOT**,
0417 per maggiori informazioni
0418
0419 * DOT: http://graphviz.org/pdf/dotguide.pdf
0420 * Graphviz: http://www.graphviz.org/content/dot-language
0421
0422 Un piccolo esempio (:ref:`it_hello_dot_file`)::
0423
0424 .. kernel-figure:: ../../../doc-guide/hello.dot
0425 :alt: ciao mondo
0426
0427 Esempio DOT
0428
0429 .. _it_hello_dot_file:
0430
0431 .. kernel-figure:: ../../../doc-guide/hello.dot
0432 :alt: ciao mondo
0433
0434 Esempio DOT
0435
0436 Tramite la direttiva ``kernel-render`` è possibile aggiungere codice specifico;
0437 ad esempio nel formato **DOT** di Graphviz.::
0438
0439 .. kernel-render:: DOT
0440 :alt: foobar digraph
0441 :caption: Codice **DOT** (Graphviz) integrato
0442
0443 digraph foo {
0444 "bar" -> "baz";
0445 }
0446
0447 La rappresentazione dipenderà dei programmi installati. Se avete Graphviz
0448 installato, vedrete un'immagine vettoriale. In caso contrario, il codice grezzo
0449 verrà rappresentato come *blocco testuale* (:ref:`it_hello_dot_render`).
0450
0451 .. _it_hello_dot_render:
0452
0453 .. kernel-render:: DOT
0454 :alt: foobar digraph
0455 :caption: Codice **DOT** (Graphviz) integrato
0456
0457 digraph foo {
0458 "bar" -> "baz";
0459 }
0460
0461 La direttiva *render* ha tutte le opzioni della direttiva *figure*, con
0462 l'aggiunta dell'opzione ``caption``. Se ``caption`` ha un valore allora
0463 un nodo *figure* viene aggiunto. Altrimenti verrà aggiunto un nodo *image*.
0464 L'opzione ``caption`` è necessaria in caso si vogliano aggiungere dei
0465 riferimenti (:ref:`it_hello_svg_render`).
0466
0467 Per la scrittura di codice **SVG**::
0468
0469 .. kernel-render:: SVG
0470 :caption: Integrare codice **SVG**
0471 :alt: so-nw-arrow
0472
0473 <?xml version="1.0" encoding="UTF-8"?>
0474 <svg xmlns="http://www.w3.org/2000/svg" version="1.1" ...>
0475 ...
0476 </svg>
0477
0478 .. _it_hello_svg_render:
0479
0480 .. kernel-render:: SVG
0481 :caption: Integrare codice **SVG**
0482 :alt: so-nw-arrow
0483
0484 <?xml version="1.0" encoding="UTF-8"?>
0485 <svg xmlns="http://www.w3.org/2000/svg"
0486 version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400">
0487 <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>
0488 <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>
0489 </svg>
