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============================================= 9Usare Sphinx per la documentazione del kernel 10============================================= 11 12Il kernel Linux usa `Sphinx`_ per la generazione della documentazione a partire 13dai file `reStructuredText`_ che si trovano nella cartella ``Documentation``. 14Per generare la documentazione in HTML o PDF, usate comandi ``make htmldocs`` o 15``make pdfdocs``. La documentazione così generata sarà disponibile nella 16cartella ``Documentation/output``. 17 18.. _Sphinx: http://www.sphinx-doc.org/ 19.. _reStructuredText: http://docutils.sourceforge.net/rst.html 20 21I file reStructuredText possono contenere delle direttive che permettono di 22includere i commenti di documentazione, o di tipo kernel-doc, dai file 23sorgenti. 24Solitamente questi commenti sono utilizzati per descrivere le funzioni, i tipi 25e l'architettura del codice. I commenti di tipo kernel-doc hanno una struttura 26e formato speciale, ma a parte questo vengono processati come reStructuredText. 27 28Inoltre, ci sono migliaia di altri documenti in formato testo sparsi nella 29cartella ``Documentation``. Alcuni di questi verranno probabilmente convertiti, 30nel tempo, in formato reStructuredText, ma la maggior parte di questi rimarranno 31in formato testo. 32 33.. _it_sphinx_install: 34 35Installazione Sphinx 36==================== 37 38I marcatori ReST utilizzati nei file in Documentation/ sono pensati per essere 39processati da ``Sphinx`` nella versione 1.7 o superiore. 40 41Esiste uno script che verifica i requisiti Sphinx. Per ulteriori dettagli 42consultate :ref:`it_sphinx-pre-install`. 43 44La maggior parte delle distribuzioni Linux forniscono Sphinx, ma l'insieme dei 45programmi e librerie è fragile e non è raro che dopo un aggiornamento di 46Sphinx, o qualche altro pacchetto Python, la documentazione non venga più 47generata correttamente. 48 49Un modo per evitare questo genere di problemi è quello di utilizzare una 50versione diversa da quella fornita dalla vostra distribuzione. Per fare questo, 51vi raccomandiamo di installare Sphinx dentro ad un ambiente virtuale usando 52``virtualenv-3`` o ``virtualenv`` a seconda di come Python 3 è stato 53pacchettizzato 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 66Riassumendo, 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 72Dopo aver eseguito ``. sphinx_2.4.4/bin/activate``, il prompt cambierà per 73indicare che state usando il nuovo ambiente. Se aprite un nuova sessione, 74prima di generare la documentazione, dovrete rieseguire questo comando per 75rientrare nell'ambiente virtuale. 76 77Generazione d'immagini 78---------------------- 79 80Il meccanismo che genera la documentazione del kernel contiene un'estensione 81capace di gestire immagini in formato Graphviz e SVG (per maggior informazioni 82vedere :ref:`it_sphinx_kfigure`). 83 84Per far si che questo funzioni, dovete installare entrambe i pacchetti 85Graphviz e ImageMagick. Il sistema di generazione della documentazione è in 86grado di procedere anche se questi pacchetti non sono installati, ma il 87risultato, ovviamente, non includerà le immagini. 88 89Generazione in PDF e LaTeX 90-------------------------- 91 92Al momento, la generazione di questi documenti è supportata solo dalle 93versioni di Sphinx superiori alla 2.4. 94 95Per la generazione di PDF e LaTeX, avrete bisogno anche del pacchetto 96``XeLaTeX`` nella versione 3.14159265 97 98Per alcune distribuzioni Linux potrebbe essere necessario installare 99anche una serie di pacchetti ``texlive`` in modo da fornire il supporto 100minimo per il funzionamento di ``XeLaTeX``. 101 102.. _it_sphinx-pre-install: 103 104Verificare le dipendenze Sphinx 105------------------------------- 106 107Esiste uno script che permette di verificare automaticamente le dipendenze di 108Sphinx. Se lo script riesce a riconoscere la vostra distribuzione, allora 109sarà in grado di darvi dei suggerimenti su come procedere per completare 110l'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 124L'impostazione predefinita prevede il controllo dei requisiti per la generazione 125di documenti html e PDF, includendo anche il supporto per le immagini, le 126espressioni matematiche e LaTeX; inoltre, presume che venga utilizzato un 127ambiente virtuale per Python. I requisiti per generare i documenti html 128sono considerati obbligatori, gli altri sono opzionali. 129 130Questo 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 140Generazione della documentazione Sphinx 141======================================= 142 143Per generare la documentazione in formato HTML o PDF si eseguono i rispettivi 144comandi ``make htmldocs`` o ``make pdfdocs``. Esistono anche altri formati 145in cui è possibile generare la documentazione; per maggiori informazioni 146potere eseguire il comando ``make help``. 147La documentazione così generata sarà disponibile nella sottocartella 148``Documentation/output``. 149 150Ovviamente, per generare la documentazione, Sphinx (``sphinx-build``) 151dev'essere installato. Se disponibile, il tema *Read the Docs* per Sphinx 152verrà utilizzato per ottenere una documentazione HTML più gradevole. 153Per la documentazione in formato PDF, invece, avrete bisogno di ``XeLaTeX` 154e di ``convert(1)`` disponibile in ImageMagick 155(https://www.imagemagick.org). \ [#ink]_ 156Tipicamente, tutti questi pacchetti sono disponibili e pacchettizzati nelle 157distribuzioni Linux. 158 159Per poter passare ulteriori opzioni a Sphinx potete utilizzare la variabile 160make ``SPHINXOPTS``. Per esempio, se volete che Sphinx sia più verboso durante 161la generazione potete usare il seguente comando ``make SPHINXOPTS=-v htmldocs``. 162 163Potete anche personalizzare l'ouptut html passando un livello aggiuntivo 164DOCS_CSS usando la rispettiva variabile d'ambiente ``DOCS_CSS``. 165 166La variable make ``SPHINXDIRS`` è utile quando si vuole generare solo una parte 167della documentazione. Per esempio, si possono generare solo di documenti in 168``Documentation/doc-guide`` eseguendo ``make SPHINXDIRS=doc-guide htmldocs``. La 169sezione dedicata alla documentazione di ``make help`` vi mostrerà quali sotto 170cartelle potete specificare. 171 172Potete 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 180Scrivere la documentazione 181========================== 182 183Aggiungere nuova documentazione è semplice: 184 1851. aggiungete un file ``.rst`` nella sottocartella ``Documentation`` 1862. 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 191Questo, di solito, è sufficiente per la documentazione più semplice (come 192quella che state leggendo ora), ma per una documentazione più elaborata è 193consigliato creare una sottocartella dedicata (o, quando possibile, utilizzarne 194una già esistente). Per esempio, il sottosistema grafico è documentato nella 195sottocartella ``Documentation/gpu``; questa documentazione è divisa in 196diversi file ``.rst`` ed un indice ``index.rst`` (con un ``toctree`` 197dedicato) a cui si fa riferimento nell'indice principale. 198 199Consultate la documentazione di `Sphinx`_ e `reStructuredText`_ per maggiori 200informazione circa le loro potenzialità. In particolare, il 201`manuale introduttivo a reStructuredText`_ di Sphinx è un buon punto da 202cui 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 208Guide linea per la documentazione del kernel 209-------------------------------------------- 210 211In questa sezione troverete alcune linee guida specifiche per la documentazione 212del 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 261Il dominio C 262------------ 263 264Il **Dominio Sphinx C** (denominato c) è adatto alla documentazione delle API C. 265Per esempio, un prototipo di una funzione: 266 267.. code-block:: rst 268 269 .. c:function:: int ioctl( int fd, int request ) 270 271Il dominio C per kernel-doc ha delle funzionalità aggiuntive. Per esempio, 272potete assegnare un nuovo nome di riferimento ad una funzione con un nome 273molto 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 280Il nome della funzione (per esempio ioctl) rimane nel testo ma il nome del suo 281riferimento cambia da ``ioctl`` a ``VIDIOC_LOG_STATUS``. Anche la voce 282nell'indice cambia in ``VIDIOC_LOG_STATUS``. 283 284Notate che per una funzione non c'è bisogno di usare ``c:func:`` per generarne 285i riferimenti nella documentazione. Grazie a qualche magica estensione a 286Sphinx, il sistema di generazione della documentazione trasformerà 287automaticamente un riferimento ad una ``funzione()`` in un riferimento 288incrociato 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 292Tabelle a liste 293--------------- 294 295Il formato ``list-table`` può essere utile per tutte quelle tabelle che non 296possono essere facilmente scritte usando il formato ASCII-art di Sphinx. Però, 297questo genere di tabelle sono illeggibili per chi legge direttamente i file di 298testo. Dunque, questo formato dovrebbe essere evitato senza forti argomenti che 299ne giustifichino l'uso. 300 301La ``flat-table`` è anch'essa una lista di liste simile alle ``list-table`` 302ma 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 315opzioni: 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 323ruoli: 324 325* ``:cspan:`` [int] colonne successive (*morecols*) 326* ``:rspan:`` [int] righe successive (*morerows*) 327 328L'esempio successivo mostra come usare questo marcatore. Il primo livello della 329nostra lista di liste è la *riga*. In una *riga* è possibile inserire solamente 330la 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 356Che 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 378Riferimenti incrociati 379---------------------- 380 381Aggiungere un riferimento incrociato da una pagina della 382documentazione ad un'altra può essere fatto scrivendo il percorso al 383file corrispondende, non serve alcuna sintassi speciale. Si possono 384usare sia percorsi assoluti che relativi. Quelli assoluti iniziano con 385"documentation/". Per esempio, potete fare riferimento a questo 386documento 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 393Se volete che il collegamento abbia un testo diverso rispetto al 394titolo del documento, allora dovrete usare la direttiva Sphinx 395``doc``. Per esempio:: 396 397 Vedere :doc:`il mio testo per il collegamento <sphinx>`. 398 399Nella maggioranza dei casi si consiglia il primo metodo perché è più 400pulito ed adatto a chi legge dai sorgenti. Se incontrare un ``:doc:`` 401che non da alcun valore, sentitevi liberi di convertirlo in un 402percorso al documento. 403 404Per informazioni riguardo ai riferimenti incrociati ai commenti 405kernel-doc per funzioni o tipi, consultate 406 407.. _it_sphinx_kfigure: 408 409Figure ed immagini 410================== 411 412Se volete aggiungere un'immagine, utilizzate le direttive ``kernel-figure`` 413e ``kernel-image``. Per esempio, per inserire una figura di un'immagine in 414formato 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 428Le direttive del kernel per figure ed immagini supportano il formato **DOT**, 429per maggiori informazioni 430 431* DOT: http://graphviz.org/pdf/dotguide.pdf 432* Graphviz: http://www.graphviz.org/content/dot-language 433 434Un 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 448Tramite la direttiva ``kernel-render`` è possibile aggiungere codice specifico; 449ad 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 459La rappresentazione dipenderà dei programmi installati. Se avete Graphviz 460installato, vedrete un'immagine vettoriale. In caso contrario, il codice grezzo 461verrà 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 473La direttiva *render* ha tutte le opzioni della direttiva *figure*, con 474l'aggiunta dell'opzione ``caption``. Se ``caption`` ha un valore allora 475un nodo *figure* viene aggiunto. Altrimenti verrà aggiunto un nodo *image*. 476L'opzione ``caption`` è necessaria in caso si vogliano aggiungere dei 477riferimenti (:ref:`it_hello_svg_render`). 478 479Per 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> 502
