.. include:: ../disclaimer-ita.rst .. note:: Per leggere la documentazione originale in inglese: :ref:`Documentation/doc-guide/index.rst <doc_guide>` Introduzione ============ Il kernel Linux usa `Sphinx`_ per la generazione della documentazione a partire dai file `reStructuredText`_ che si trovano nella cartella ``Documentation``. Per generare la documentazione in HTML o PDF, usate comandi ``make htmldocs`` o ``make pdfdocs``. La documentazione così generata sarà disponibile nella cartella ``Documentation/output``. .. _Sphinx: http://www.sphinx-doc.org/ .. _reStructuredText: http://docutils.sourceforge.net/rst.html I file reStructuredText possono contenere delle direttive che permettono di includere i commenti di documentazione, o di tipo kernel-doc, dai file sorgenti. Solitamente questi commenti sono utilizzati per descrivere le funzioni, i tipi e l'architettura del codice. I commenti di tipo kernel-doc hanno una struttura e formato speciale, ma a parte questo vengono processati come reStructuredText. Inoltre, ci sono migliaia di altri documenti in formato testo sparsi nella cartella ``Documentation``. Alcuni di questi verranno probabilmente convertiti, nel tempo, in formato reStructuredText, ma la maggior parte di questi rimarranno in formato testo. .. _it_sphinx_install: Installazione Sphinx ==================== I marcatori ReST utilizzati nei file in Documentation/ sono pensati per essere processati da ``Sphinx`` nella versione 1.3 o superiore. Se desiderate produrre un documento PDF è raccomandato l'utilizzo di una versione superiore alle 1.4.6. Esiste uno script che verifica i requisiti Sphinx. Per ulteriori dettagli consultate :ref:`it_sphinx-pre-install`. La maggior parte delle distribuzioni Linux forniscono Sphinx, ma l'insieme dei programmi e librerie è fragile e non è raro che dopo un aggiornamento di Sphinx, o qualche altro pacchetto Python, la documentazione non venga più generata correttamente. Un modo per evitare questo genere di problemi è quello di utilizzare una versione diversa da quella fornita dalla vostra distribuzione. Per fare questo, vi raccomandiamo di installare Sphinx dentro ad un ambiente virtuale usando ``virtualenv-3`` o ``virtualenv`` a seconda di come Python 3 è stato pacchettizzato dalla vostra distribuzione. .. note:: #) Le versioni di Sphinx inferiori alla 1.5 non funzionano bene con il pacchetto Python docutils versione 0.13.1 o superiore. Se volete usare queste versioni, allora dovere eseguire ``pip install 'docutils==0.12'``. #) Viene raccomandato l'uso del tema RTD per la documentazione in HTML. A seconda della versione di Sphinx, potrebbe essere necessaria l'installazione tramite il comando ``pip install sphinx_rtd_theme``. #) Alcune pagine ReST contengono delle formule matematiche. A causa del modo in cui Sphinx funziona, queste espressioni sono scritte utilizzando LaTeX. Per una corretta interpretazione, è necessario aver installato texlive con i pacchetti amdfonts e amsmath. Riassumendo, se volete installare la versione 1.4.9 di Sphinx dovete eseguire:: $ virtualenv sphinx_1.4 $ . sphinx_1.4/bin/activate (sphinx_1.4) $ pip install -r Documentation/sphinx/requirements.txt Dopo aver eseguito ``. sphinx_1.4/bin/activate``, il prompt cambierà per indicare che state usando il nuovo ambiente. Se aprite un nuova sessione, prima di generare la documentazione, dovrete rieseguire questo comando per rientrare nell'ambiente virtuale. Generazione d'immagini ---------------------- Il meccanismo che genera la documentazione del kernel contiene un'estensione capace di gestire immagini in formato Graphviz e SVG (per maggior informazioni vedere :ref:`it_sphinx_kfigure`). Per far si che questo funzioni, dovete installare entrambe i pacchetti Graphviz e ImageMagick. Il sistema di generazione della documentazione è in grado di procedere anche se questi pacchetti non sono installati, ma il risultato, ovviamente, non includerà le immagini. Generazione in PDF e LaTeX -------------------------- Al momento, la generazione di questi documenti è supportata solo dalle versioni di Sphinx superiori alla 1.4. Per la generazione di PDF e LaTeX, avrete bisogno anche del pacchetto ``XeLaTeX`` nella versione 3.14159265 Per alcune distribuzioni Linux potrebbe essere necessario installare anche una serie di pacchetti ``texlive`` in modo da fornire il supporto minimo per il funzionamento di ``XeLaTeX``. .. _it_sphinx-pre-install: Verificare le dipendenze Sphinx ------------------------------- Esiste uno script che permette di verificare automaticamente le dipendenze di Sphinx. Se lo script riesce a riconoscere la vostra distribuzione, allora sarà in grado di darvi dei suggerimenti su come procedere per completare l'installazione:: $ ./scripts/sphinx-pre-install Checking if the needed tools for Fedora release 26 (Twenty Six) are available Warning: better to also install "texlive-luatex85". You should run: sudo dnf install -y texlive-luatex85 /usr/bin/virtualenv sphinx_1.4 . sphinx_1.4/bin/activate pip install -r Documentation/sphinx/requirements.txt Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468. L'impostazione predefinita prevede il controllo dei requisiti per la generazione di documenti html e PDF, includendo anche il supporto per le immagini, le espressioni matematiche e LaTeX; inoltre, presume che venga utilizzato un ambiente virtuale per Python. I requisiti per generare i documenti html sono considerati obbligatori, gli altri sono opzionali. Questo script ha i seguenti parametri: ``--no-pdf`` Disabilita i controlli per la generazione di PDF; ``--no-virtualenv`` Utilizza l'ambiente predefinito dal sistema operativo invece che l'ambiente virtuale per Python; Generazione della documentazione Sphinx ======================================= Per generare la documentazione in formato HTML o PDF si eseguono i rispettivi comandi ``make htmldocs`` o ``make pdfdocs``. Esistono anche altri formati in cui è possibile generare la documentazione; per maggiori informazioni potere eseguire il comando ``make help``. La documentazione così generata sarà disponibile nella sottocartella ``Documentation/output``. Ovviamente, per generare la documentazione, Sphinx (``sphinx-build``) dev'essere installato. Se disponibile, il tema *Read the Docs* per Sphinx verrà utilizzato per ottenere una documentazione HTML più gradevole. Per la documentazione in formato PDF, invece, avrete bisogno di ``XeLaTeX` e di ``convert(1)`` disponibile in ImageMagick (https://www.imagemagick.org). Tipicamente, tutti questi pacchetti sono disponibili e pacchettizzati nelle distribuzioni Linux. Per poter passare ulteriori opzioni a Sphinx potete utilizzare la variabile make ``SPHINXOPTS``. Per esempio, se volete che Sphinx sia più verboso durante la generazione potete usare il seguente comando ``make SPHINXOPTS=-v htmldocs``. Potete eliminare la documentazione generata tramite il comando ``make cleandocs``. Scrivere la documentazione ========================== Aggiungere nuova documentazione è semplice: 1. aggiungete un file ``.rst`` nella sottocartella ``Documentation`` 2. aggiungete un riferimento ad esso nell'indice (`TOC tree`_) in ``Documentation/index.rst``. .. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html Questo, di solito, è sufficiente per la documentazione più semplice (come quella che state leggendo ora), ma per una documentazione più elaborata è consigliato creare una sottocartella dedicata (o, quando possibile, utilizzarne una già esistente). Per esempio, il sottosistema grafico è documentato nella sottocartella ``Documentation/gpu``; questa documentazione è divisa in diversi file ``.rst`` ed un indice ``index.rst`` (con un ``toctree`` dedicato) a cui si fa riferimento nell'indice principale. Consultate la documentazione di `Sphinx`_ e `reStructuredText`_ per maggiori informazione circa le loro potenzialità. In particolare, il `manuale introduttivo a reStructuredText`_ di Sphinx è un buon punto da cui cominciare. Esistono, inoltre, anche alcuni `costruttori specifici per Sphinx`_. .. _`manuale introduttivo a reStructuredText`: http://www.sphinx-doc.org/en/stable/rest.html .. _`costruttori specifici per Sphinx`: http://www.sphinx-doc.org/en/stable/markup/index.html Guide linea per la documentazione del kernel -------------------------------------------- In questa sezione troverete alcune linee guida specifiche per la documentazione del kernel: * Non esagerate con i costrutti di reStructuredText. Mantenete la documentazione semplice. La maggior parte della documentazione dovrebbe essere testo semplice con una strutturazione minima che permetta la conversione in diversi formati. * Mantenete la strutturazione il più fedele possibile all'originale quando convertite un documento in formato reStructuredText. * Aggiornate i contenuti quando convertite della documentazione, non limitatevi solo alla formattazione. * Mantenete la decorazione dei livelli di intestazione come segue: 1. ``=`` con una linea superiore per il titolo del documento:: ====== Titolo ====== 2. ``=`` per i capitoli:: Capitoli ======== 3. ``-`` per le sezioni:: Sezioni ------- 4. ``~`` per le sottosezioni:: Sottosezioni ~~~~~~~~~~~~ Sebbene RST non forzi alcun ordine specifico (*Piuttosto che imporre un numero ed un ordine fisso di decorazioni, l'ordine utilizzato sarà quello incontrato*), avere uniformità dei livelli principali rende più semplice la lettura dei documenti. * Per inserire blocchi di testo con caratteri a dimensione fissa (codici di esempio, casi d'uso, eccetera): utilizzate ``::`` quando non è necessario evidenziare la sintassi, specialmente per piccoli frammenti; invece, utilizzate ``.. code-block:: <language>`` per blocchi di più lunghi che potranno beneficiare dell'avere la sintassi evidenziata. Il dominio C ------------ Il **Dominio Sphinx C** (denominato c) è adatto alla documentazione delle API C. Per esempio, un prototipo di una funzione: .. code-block:: rst .. c:function:: int ioctl( int fd, int request ) Il dominio C per kernel-doc ha delle funzionalità aggiuntive. Per esempio, potete assegnare un nuovo nome di riferimento ad una funzione con un nome molto comune come ``open`` o ``ioctl``: .. code-block:: rst .. c:function:: int ioctl( int fd, int request ) :name: VIDIOC_LOG_STATUS Il nome della funzione (per esempio ioctl) rimane nel testo ma il nome del suo riferimento cambia da ``ioctl`` a ``VIDIOC_LOG_STATUS``. Anche la voce nell'indice cambia in ``VIDIOC_LOG_STATUS`` e si potrà quindi fare riferimento a questa funzione scrivendo: .. code-block:: rst :c:func:`VIDIOC_LOG_STATUS` Tabelle a liste --------------- Raccomandiamo l'uso delle tabelle in formato lista (*list table*). Le tabelle in formato lista sono liste di liste. In confronto all'ASCII-art potrebbero non apparire di facile lettura nei file in formato testo. Il loro vantaggio è che sono facili da creare o modificare e che la differenza di una modifica è molto più significativa perché limitata alle modifiche del contenuto. La ``flat-table`` è anch'essa una lista di liste simile alle ``list-table`` ma con delle funzionalità aggiuntive: * column-span: col ruolo ``cspan`` una cella può essere estesa attraverso colonne successive * raw-span: col ruolo ``rspan`` una cella può essere estesa attraverso righe successive * auto-span: la cella più a destra viene estesa verso destra per compensare la mancanza di celle. Con l'opzione ``:fill-cells:`` questo comportamento può essere cambiato da *auto-span* ad *auto-fill*, il quale inserisce automaticamente celle (vuote) invece che estendere l'ultima. opzioni: * ``:header-rows:`` [int] conta le righe di intestazione * ``:stub-columns:`` [int] conta le colonne di stub * ``:widths:`` [[int] [int] ... ] larghezza delle colonne * ``:fill-cells:`` invece di estendere automaticamente una cella su quelle mancanti, ne crea di vuote. ruoli: * ``:cspan:`` [int] colonne successive (*morecols*) * ``:rspan:`` [int] righe successive (*morerows*) L'esempio successivo mostra come usare questo marcatore. Il primo livello della nostra lista di liste è la *riga*. In una *riga* è possibile inserire solamente la lista di celle che compongono la *riga* stessa. Fanno eccezione i *commenti* ( ``..`` ) ed i *collegamenti* (per esempio, un riferimento a ``:ref:`last row <last row>``` / :ref:`last row <it last row>`) .. code-block:: rst .. flat-table:: table title :widths: 2 1 1 3 * - head col 1 - head col 2 - head col 3 - head col 4 * - column 1 - field 1.1 - field 1.2 with autospan * - column 2 - field 2.1 - :rspan:`1` :cspan:`1` field 2.2 - 3.3 * .. _`it last row`: - column 3 Che verrà rappresentata nel seguente modo: .. flat-table:: table title :widths: 2 1 1 3 * - head col 1 - head col 2 - head col 3 - head col 4 * - column 1 - field 1.1 - field 1.2 with autospan * - column 2 - field 2.1 - :rspan:`1` :cspan:`1` field 2.2 - 3.3 * .. _`it last row`: - column 3 .. _it_sphinx_kfigure: Figure ed immagini ================== Se volete aggiungere un'immagine, utilizzate le direttive ``kernel-figure`` e ``kernel-image``. Per esempio, per inserire una figura di un'immagine in formato SVG:: .. kernel-figure:: ../../../doc-guide/svg_image.svg :alt: una semplice immagine SVG Una semplice immagine SVG .. _it_svg_image_example: .. kernel-figure:: ../../../doc-guide/svg_image.svg :alt: una semplice immagine SVG Una semplice immagine SVG Le direttive del kernel per figure ed immagini supportano il formato **DOT**, per maggiori informazioni * DOT: http://graphviz.org/pdf/dotguide.pdf * Graphviz: http://www.graphviz.org/content/dot-language Un piccolo esempio (:ref:`it_hello_dot_file`):: .. kernel-figure:: ../../../doc-guide/hello.dot :alt: ciao mondo Esempio DOT .. _it_hello_dot_file: .. kernel-figure:: ../../../doc-guide/hello.dot :alt: ciao mondo Esempio DOT Tramite la direttiva ``kernel-render`` è possibile aggiungere codice specifico; ad esempio nel formato **DOT** di Graphviz.:: .. kernel-render:: DOT :alt: foobar digraph :caption: Codice **DOT** (Graphviz) integrato digraph foo { "bar" -> "baz"; } La rappresentazione dipenderà dei programmi installati. Se avete Graphviz installato, vedrete un'immagine vettoriale. In caso contrario, il codice grezzo verrà rappresentato come *blocco testuale* (:ref:`it_hello_dot_render`). .. _it_hello_dot_render: .. kernel-render:: DOT :alt: foobar digraph :caption: Codice **DOT** (Graphviz) integrato digraph foo { "bar" -> "baz"; } La direttiva *render* ha tutte le opzioni della direttiva *figure*, con l'aggiunta dell'opzione ``caption``. Se ``caption`` ha un valore allora un nodo *figure* viene aggiunto. Altrimenti verrà aggiunto un nodo *image*. L'opzione ``caption`` è necessaria in caso si vogliano aggiungere dei riferimenti (:ref:`it_hello_svg_render`). Per la scrittura di codice **SVG**:: .. kernel-render:: SVG :caption: Integrare codice **SVG** :alt: so-nw-arrow <?xml version="1.0" encoding="UTF-8"?> <svg xmlns="http://www.w3.org/2000/svg" version="1.1" ...> ... </svg> .. _it_hello_svg_render: .. kernel-render:: SVG :caption: Integrare codice **SVG** :alt: so-nw-arrow <?xml version="1.0" encoding="UTF-8"?> <svg xmlns="http://www.w3.org/2000/svg" version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400"> <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/> <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/> </svg>