486 lines
17 KiB
ReStructuredText
486 lines
17 KiB
ReStructuredText
.. include:: ../disclaimer-ita.rst
|
|
|
|
.. note:: Per leggere la documentazione originale in inglese:
|
|
:ref:`Documentation/doc-guide/index.rst <doc_guide>`
|
|
|
|
.. _it_sphinxdoc:
|
|
|
|
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.7 o superiore.
|
|
|
|
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::
|
|
|
|
#) 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 2.4.4 di Sphinx dovete eseguire::
|
|
|
|
$ virtualenv sphinx_2.4.4
|
|
$ . sphinx_2.4.4/bin/activate
|
|
(sphinx_2.4.4) $ pip install -r Documentation/sphinx/requirements.txt
|
|
|
|
Dopo aver eseguito ``. sphinx_2.4.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 2.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_2.4.4
|
|
. sphinx_2.4.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 più lunghi che
|
|
beneficeranno della sintassi evidenziata. Per un breve pezzo di codice da
|
|
inserire nel testo, usate \`\`.
|
|
|
|
|
|
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``.
|
|
|
|
Notate che per una funzione non c'è bisogno di usare ``c:func:`` per generarne
|
|
i riferimenti nella documentazione. Grazie a qualche magica estensione a
|
|
Sphinx, il sistema di generazione della documentazione trasformerà
|
|
automaticamente un riferimento ad una ``funzione()`` in un riferimento
|
|
incrociato quando questa ha una voce nell'indice. Se trovate degli usi di
|
|
``c:func:`` nella documentazione del kernel, sentitevi liberi di rimuoverli.
|
|
|
|
|
|
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
|
|
|
|
* - row 1
|
|
- field 1.1
|
|
- field 1.2 with autospan
|
|
|
|
* - row 2
|
|
- field 2.1
|
|
- :rspan:`1` :cspan:`1` field 2.2 - 3.3
|
|
|
|
* .. _`it last row`:
|
|
|
|
- row 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
|
|
|
|
* - row 1
|
|
- field 1.1
|
|
- field 1.2 with autospan
|
|
|
|
* - row 2
|
|
- field 2.1
|
|
- :rspan:`1` :cspan:`1` field 2.2 - 3.3
|
|
|
|
* .. _`it last row`:
|
|
|
|
- row 3
|
|
|
|
Riferimenti incrociati
|
|
----------------------
|
|
|
|
Aggiungere un riferimento incrociato da una pagina della
|
|
documentazione ad un'altra può essere fatto scrivendo il percorso al
|
|
file corrispondende, non serve alcuna sintassi speciale. Si possono
|
|
usare sia percorsi assoluti che relativi. Quelli assoluti iniziano con
|
|
"documentation/". Per esempio, potete fare riferimento a questo
|
|
documento in uno dei seguenti modi (da notare che l'estensione
|
|
``.rst`` è necessaria)::
|
|
|
|
Vedere Documentation/doc-guide/sphinx.rst. Questo funziona sempre
|
|
Guardate pshinx.rst, che si trova nella stessa cartella.
|
|
Leggete ../sphinx.rst, che si trova nella cartella precedente.
|
|
|
|
Se volete che il collegamento abbia un testo diverso rispetto al
|
|
titolo del documento, allora dovrete usare la direttiva Sphinx
|
|
``doc``. Per esempio::
|
|
|
|
Vedere :doc:`il mio testo per il collegamento <sphinx>`.
|
|
|
|
Nella maggioranza dei casi si consiglia il primo metodo perché è più
|
|
pulito ed adatto a chi legge dai sorgenti. Se incontrare un ``:doc:``
|
|
che non da alcun valore, sentitevi liberi di convertirlo in un
|
|
percorso al documento.
|
|
|
|
Per informazioni riguardo ai riferimenti incrociati ai commenti
|
|
kernel-doc per funzioni o tipi, consultate
|
|
|
|
.. _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 (:ref:`it_svg_image_example`)::
|
|
|
|
.. 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>
|