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