502 lines · plain
1.. include:: ../disclaimer-ita.rst2 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 kernel10=============================================11 12Il kernel Linux usa `Sphinx`_ per la generazione della documentazione a partire13dai file `reStructuredText`_ che si trovano nella cartella ``Documentation``.14Per generare la documentazione in HTML o PDF, usate comandi ``make htmldocs`` o15``make pdfdocs``. La documentazione così generata sarà disponibile nella16cartella ``Documentation/output``.17 18.. _Sphinx: http://www.sphinx-doc.org/19.. _reStructuredText: http://docutils.sourceforge.net/rst.html20 21I file reStructuredText possono contenere delle direttive che permettono di22includere i commenti di documentazione, o di tipo kernel-doc, dai file23sorgenti.24Solitamente questi commenti sono utilizzati per descrivere le funzioni, i tipi25e l'architettura del codice. I commenti di tipo kernel-doc hanno una struttura26e formato speciale, ma a parte questo vengono processati come reStructuredText.27 28Inoltre, ci sono migliaia di altri documenti in formato testo sparsi nella29cartella ``Documentation``. Alcuni di questi verranno probabilmente convertiti,30nel tempo, in formato reStructuredText, ma la maggior parte di questi rimarranno31in formato testo.32 33.. _it_sphinx_install:34 35Installazione Sphinx36====================37 38I marcatori ReST utilizzati nei file in Documentation/ sono pensati per essere39processati da ``Sphinx`` nella versione 1.7 o superiore.40 41Esiste uno script che verifica i requisiti Sphinx. Per ulteriori dettagli42consultate :ref:`it_sphinx-pre-install`.43 44La maggior parte delle distribuzioni Linux forniscono Sphinx, ma l'insieme dei45programmi e librerie è fragile e non è raro che dopo un aggiornamento di46Sphinx, o qualche altro pacchetto Python, la documentazione non venga più47generata correttamente.48 49Un modo per evitare questo genere di problemi è quello di utilizzare una50versione diversa da quella fornita dalla vostra distribuzione. Per fare questo,51vi raccomandiamo di installare Sphinx dentro ad un ambiente virtuale usando52``virtualenv-3`` o ``virtualenv`` a seconda di come Python 3 è stato53pacchettizzato 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 necessaria59 l'installazione tramite il comando ``pip install sphinx_rtd_theme``.60 61 #) Alcune pagine ReST contengono delle formule matematiche. A causa del62 modo in cui Sphinx funziona, queste espressioni sono scritte63 utilizzando LaTeX. Per una corretta interpretazione, è necessario aver64 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.469 $ . sphinx_2.4.4/bin/activate70 (sphinx_2.4.4) $ pip install -r Documentation/sphinx/requirements.txt71 72Dopo aver eseguito ``. sphinx_2.4.4/bin/activate``, il prompt cambierà per73indicare che state usando il nuovo ambiente. Se aprite un nuova sessione,74prima di generare la documentazione, dovrete rieseguire questo comando per75rientrare nell'ambiente virtuale.76 77Generazione d'immagini78----------------------79 80Il meccanismo che genera la documentazione del kernel contiene un'estensione81capace di gestire immagini in formato Graphviz e SVG (per maggior informazioni82vedere :ref:`it_sphinx_kfigure`).83 84Per far si che questo funzioni, dovete installare entrambe i pacchetti85Graphviz e ImageMagick. Il sistema di generazione della documentazione è in86grado di procedere anche se questi pacchetti non sono installati, ma il87risultato, ovviamente, non includerà le immagini.88 89Generazione in PDF e LaTeX90--------------------------91 92Al momento, la generazione di questi documenti è supportata solo dalle93versioni di Sphinx superiori alla 2.4.94 95Per la generazione di PDF e LaTeX, avrete bisogno anche del pacchetto96``XeLaTeX`` nella versione 3.1415926597 98Per alcune distribuzioni Linux potrebbe essere necessario installare99anche una serie di pacchetti ``texlive`` in modo da fornire il supporto100minimo per il funzionamento di ``XeLaTeX``.101 102.. _it_sphinx-pre-install:103 104Verificare le dipendenze Sphinx105-------------------------------106 107Esiste uno script che permette di verificare automaticamente le dipendenze di108Sphinx. Se lo script riesce a riconoscere la vostra distribuzione, allora109sarà in grado di darvi dei suggerimenti su come procedere per completare110l'installazione::111 112 $ ./scripts/sphinx-pre-install113 Checking if the needed tools for Fedora release 26 (Twenty Six) are available114 Warning: better to also install "texlive-luatex85".115 You should run:116 117 sudo dnf install -y texlive-luatex85118 /usr/bin/virtualenv sphinx_2.4.4119 . sphinx_2.4.4/bin/activate120 pip install -r Documentation/sphinx/requirements.txt121 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 generazione125di documenti html e PDF, includendo anche il supporto per le immagini, le126espressioni matematiche e LaTeX; inoltre, presume che venga utilizzato un127ambiente virtuale per Python. I requisiti per generare i documenti html128sono 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 che137 l'ambiente virtuale per Python;138 139 140Generazione della documentazione Sphinx141=======================================142 143Per generare la documentazione in formato HTML o PDF si eseguono i rispettivi144comandi ``make htmldocs`` o ``make pdfdocs``. Esistono anche altri formati145in cui è possibile generare la documentazione; per maggiori informazioni146potere eseguire il comando ``make help``.147La documentazione così generata sarà disponibile nella sottocartella148``Documentation/output``.149 150Ovviamente, per generare la documentazione, Sphinx (``sphinx-build``)151dev'essere installato. Se disponibile, il tema *Read the Docs* per Sphinx152verrà 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 ImageMagick155(https://www.imagemagick.org). \ [#ink]_156Tipicamente, tutti questi pacchetti sono disponibili e pacchettizzati nelle157distribuzioni Linux.158 159Per poter passare ulteriori opzioni a Sphinx potete utilizzare la variabile160make ``SPHINXOPTS``. Per esempio, se volete che Sphinx sia più verboso durante161la generazione potete usare il seguente comando ``make SPHINXOPTS=-v htmldocs``.162 163Potete anche personalizzare l'ouptut html passando un livello aggiuntivo164DOCS_CSS usando la rispettiva variabile d'ambiente ``DOCS_CSS``.165 166La variable make ``SPHINXDIRS`` è utile quando si vuole generare solo una parte167della documentazione. Per esempio, si possono generare solo di documenti in168``Documentation/doc-guide`` eseguendo ``make SPHINXDIRS=doc-guide htmldocs``. La169sezione dedicata alla documentazione di ``make help`` vi mostrerà quali sotto170cartelle potete specificare.171 172Potete eliminare la documentazione generata tramite il comando173``make cleandocs``.174 175.. [#ink] Avere installato anche ``inkscape(1)`` dal progetto Inkscape ()176 potrebbe aumentare la qualità delle immagini che verranno integrate177 nel documento PDF, specialmente per quando si usando rilasci del178 kernel uguali o superiori a 5.18179 180Scrivere la documentazione181==========================182 183Aggiungere nuova documentazione è semplice:184 1851. aggiungete un file ``.rst`` nella sottocartella ``Documentation``1862. aggiungete un riferimento ad esso nell'indice (`TOC tree`_) in187 ``Documentation/index.rst``.188 189.. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html190 191Questo, di solito, è sufficiente per la documentazione più semplice (come192quella che state leggendo ora), ma per una documentazione più elaborata è193consigliato creare una sottocartella dedicata (o, quando possibile, utilizzarne194una già esistente). Per esempio, il sottosistema grafico è documentato nella195sottocartella ``Documentation/gpu``; questa documentazione è divisa in196diversi 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 maggiori200informazione circa le loro potenzialità. In particolare, il201`manuale introduttivo a reStructuredText`_ di Sphinx è un buon punto da202cui cominciare. Esistono, inoltre, anche alcuni203`costruttori specifici per Sphinx`_.204 205.. _`manuale introduttivo a reStructuredText`: http://www.sphinx-doc.org/en/stable/rest.html206.. _`costruttori specifici per Sphinx`: http://www.sphinx-doc.org/en/stable/markup/index.html207 208Guide linea per la documentazione del kernel209--------------------------------------------210 211In questa sezione troverete alcune linee guida specifiche per la documentazione212del kernel:213 214* Non esagerate con i costrutti di reStructuredText. Mantenete la215 documentazione semplice. La maggior parte della documentazione dovrebbe216 essere testo semplice con una strutturazione minima che permetta la217 conversione in diversi formati.218 219* Mantenete la strutturazione il più fedele possibile all'originale quando220 convertite un documento in formato reStructuredText.221 222* Aggiornate i contenuti quando convertite della documentazione, non limitatevi223 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 Titolo231 ======232 233 2. ``=`` per i capitoli::234 235 Capitoli236 ========237 238 3. ``-`` per le sezioni::239 240 Sezioni241 -------242 243 4. ``~`` per le sottosezioni::244 245 Sottosezioni246 ~~~~~~~~~~~~247 248 Sebbene RST non forzi alcun ordine specifico (*Piuttosto che imporre249 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 di254 esempio, casi d'uso, eccetera): utilizzate ``::`` quando non è necessario255 evidenziare la sintassi, specialmente per piccoli frammenti; invece,256 utilizzate ``.. code-block:: <language>`` per blocchi più lunghi che257 beneficeranno della sintassi evidenziata. Per un breve pezzo di codice da258 inserire nel testo, usate \`\`.259 260 261Il dominio C262------------263 264Il **Dominio Sphinx C** (denominato c) è adatto alla documentazione delle API C.265Per esempio, un prototipo di una funzione:266 267.. code-block:: rst268 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 nome273molto comune come ``open`` o ``ioctl``:274 275.. code-block:: rst276 277 .. c:function:: int ioctl( int fd, int request )278 :name: VIDIOC_LOG_STATUS279 280Il nome della funzione (per esempio ioctl) rimane nel testo ma il nome del suo281riferimento cambia da ``ioctl`` a ``VIDIOC_LOG_STATUS``. Anche la voce282nell'indice cambia in ``VIDIOC_LOG_STATUS``.283 284Notate che per una funzione non c'è bisogno di usare ``c:func:`` per generarne285i riferimenti nella documentazione. Grazie a qualche magica estensione a286Sphinx, il sistema di generazione della documentazione trasformerà287automaticamente un riferimento ad una ``funzione()`` in un riferimento288incrociato quando questa ha una voce nell'indice. Se trovate degli usi di289``c:func:`` nella documentazione del kernel, sentitevi liberi di rimuoverli.290 291 292Tabelle a liste293---------------294 295Il formato ``list-table`` può essere utile per tutte quelle tabelle che non296possono essere facilmente scritte usando il formato ASCII-art di Sphinx. Però,297questo genere di tabelle sono illeggibili per chi legge direttamente i file di298testo. Dunque, questo formato dovrebbe essere evitato senza forti argomenti che299ne 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 attraverso305 colonne successive306 307* raw-span: col ruolo ``rspan`` una cella può essere estesa attraverso308 righe successive309 310* auto-span: la cella più a destra viene estesa verso destra per compensare311 la mancanza di celle. Con l'opzione ``:fill-cells:`` questo comportamento312 può essere cambiato da *auto-span* ad *auto-fill*, il quale inserisce313 automaticamente celle (vuote) invece che estendere l'ultima.314 315opzioni:316 317* ``:header-rows:`` [int] conta le righe di intestazione318* ``:stub-columns:`` [int] conta le colonne di stub319* ``:widths:`` [[int] [int] ... ] larghezza delle colonne320* ``:fill-cells:`` invece di estendere automaticamente una cella su quelle321 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 della329nostra lista di liste è la *riga*. In una *riga* è possibile inserire solamente330la lista di celle che compongono la *riga* stessa. Fanno eccezione i *commenti*331( ``..`` ) ed i *collegamenti* (per esempio, un riferimento a332``:ref:`last row <last row>``` / :ref:`last row <it last row>`)333 334.. code-block:: rst335 336 .. flat-table:: table title337 :widths: 2 1 1 3338 339 * - head col 1340 - head col 2341 - head col 3342 - head col 4343 344 * - row 1345 - field 1.1346 - field 1.2 with autospan347 348 * - row 2349 - field 2.1350 - :rspan:`1` :cspan:`1` field 2.2 - 3.3351 352 * .. _`it last row`:353 354 - row 3355 356Che verrà rappresentata nel seguente modo:357 358 .. flat-table:: table title359 :widths: 2 1 1 3360 361 * - head col 1362 - head col 2363 - head col 3364 - head col 4365 366 * - row 1367 - field 1.1368 - field 1.2 with autospan369 370 * - row 2371 - field 2.1372 - :rspan:`1` :cspan:`1` field 2.2 - 3.3373 374 * .. _`it last row`:375 376 - row 3377 378Riferimenti incrociati379----------------------380 381Aggiungere un riferimento incrociato da una pagina della382documentazione ad un'altra può essere fatto scrivendo il percorso al383file corrispondende, non serve alcuna sintassi speciale. Si possono384usare sia percorsi assoluti che relativi. Quelli assoluti iniziano con385"documentation/". Per esempio, potete fare riferimento a questo386documento in uno dei seguenti modi (da notare che l'estensione387``.rst`` è necessaria)::388 389 Vedere Documentation/doc-guide/sphinx.rst. Questo funziona sempre390 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 al394titolo del documento, allora dovrete usare la direttiva Sphinx395``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 un402percorso al documento.403 404Per informazioni riguardo ai riferimenti incrociati ai commenti405kernel-doc per funzioni o tipi, consultate406 407.. _it_sphinx_kfigure:408 409Figure ed immagini410==================411 412Se volete aggiungere un'immagine, utilizzate le direttive ``kernel-figure``413e ``kernel-image``. Per esempio, per inserire una figura di un'immagine in414formato SVG (:ref:`it_svg_image_example`)::415 416 .. kernel-figure:: ../../../doc-guide/svg_image.svg417 :alt: una semplice immagine SVG418 419 Una semplice immagine SVG420 421.. _it_svg_image_example:422 423.. kernel-figure:: ../../../doc-guide/svg_image.svg424 :alt: una semplice immagine SVG425 426 Una semplice immagine SVG427 428Le direttive del kernel per figure ed immagini supportano il formato **DOT**,429per maggiori informazioni430 431* DOT: http://graphviz.org/pdf/dotguide.pdf432* Graphviz: http://www.graphviz.org/content/dot-language433 434Un piccolo esempio (:ref:`it_hello_dot_file`)::435 436 .. kernel-figure:: ../../../doc-guide/hello.dot437 :alt: ciao mondo438 439 Esempio DOT440 441.. _it_hello_dot_file:442 443.. kernel-figure:: ../../../doc-guide/hello.dot444 :alt: ciao mondo445 446 Esempio DOT447 448Tramite la direttiva ``kernel-render`` è possibile aggiungere codice specifico;449ad esempio nel formato **DOT** di Graphviz.::450 451 .. kernel-render:: DOT452 :alt: foobar digraph453 :caption: Codice **DOT** (Graphviz) integrato454 455 digraph foo {456 "bar" -> "baz";457 }458 459La rappresentazione dipenderà dei programmi installati. Se avete Graphviz460installato, vedrete un'immagine vettoriale. In caso contrario, il codice grezzo461verrà rappresentato come *blocco testuale* (:ref:`it_hello_dot_render`).462 463.. _it_hello_dot_render:464 465.. kernel-render:: DOT466 :alt: foobar digraph467 :caption: Codice **DOT** (Graphviz) integrato468 469 digraph foo {470 "bar" -> "baz";471 }472 473La direttiva *render* ha tutte le opzioni della direttiva *figure*, con474l'aggiunta dell'opzione ``caption``. Se ``caption`` ha un valore allora475un nodo *figure* viene aggiunto. Altrimenti verrà aggiunto un nodo *image*.476L'opzione ``caption`` è necessaria in caso si vogliano aggiungere dei477riferimenti (:ref:`it_hello_svg_render`).478 479Per la scrittura di codice **SVG**::480 481 .. kernel-render:: SVG482 :caption: Integrare codice **SVG**483 :alt: so-nw-arrow484 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:: SVG493 :caption: Integrare codice **SVG**494 :alt: so-nw-arrow495 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