it_IT/doc-guide/sphinx.rst

3 .. note:: Per leggere la documentazione originale in inglese:
9 Usare Sphinx per la documentazione del kernel
12 Il kernel Linux usa `Sphinx`_ per la generazione della documentazione a partire
14 Per generare la documentazione in HTML o PDF, usate comandi ``make htmldocs`` o
24 Solitamente questi commenti sono utilizzati per descrivere le funzioni, i tipi
38 I marcatori ReST utilizzati nei file in Documentation/ sono pensati per essere
41 Esiste uno script che verifica i requisiti Sphinx. Per ulteriori dettagli
49 Un modo per evitare questo genere di problemi è quello di utilizzare una
50 versione diversa da quella fornita dalla vostra distribuzione. Per fare questo,
57    #) Viene raccomandato l'uso del tema RTD per la documentazione in HTML.
63       utilizzando LaTeX. Per una corretta interpretazione, è necessario aver
72 Dopo aver eseguito ``. sphinx_2.4.4/bin/activate``, il prompt cambierà per
74 prima di generare la documentazione, dovrete rieseguire questo comando per
81 capace di gestire immagini in formato Graphviz e SVG (per maggior informazioni
84 Per far si che questo funzioni, dovete installare entrambe i pacchetti
95 Per la generazione di PDF e LaTeX, avrete bisogno anche del pacchetto
98 Per alcune distribuzioni Linux potrebbe essere necessario installare
100 minimo per il funzionamento di ``XeLaTeX``.
109 sarà in grado di darvi dei suggerimenti su come procedere per completare
124 L'impostazione predefinita prevede il controllo dei requisiti per la generazione
125 di documenti html e PDF, includendo anche il supporto per le immagini, le
127 ambiente virtuale per Python. I requisiti per generare i documenti html
133 	Disabilita i controlli per la generazione di PDF;
137 	l'ambiente virtuale per Python;
143 Per generare la documentazione in formato HTML o PDF si eseguono i rispettivi
145 in cui è possibile generare la documentazione; per maggiori informazioni
150 Ovviamente, per generare la documentazione, Sphinx (``sphinx-build``)
151 dev'essere installato. Se disponibile, il tema *Read the Docs* per Sphinx
152 verrà utilizzato per ottenere una documentazione HTML più gradevole.
153 Per la documentazione in formato PDF, invece, avrete bisogno di ``XeLaTeX`
159 Per poter passare ulteriori opzioni a Sphinx potete utilizzare la variabile
160 make ``SPHINXOPTS``. Per esempio, se volete che Sphinx sia più verboso durante
167 della documentazione. Per esempio, si possono generare solo di documenti in
177           nel documento PDF, specialmente per quando si usando rilasci del
191 Questo, di solito, è sufficiente per la documentazione più semplice (come
192 quella che state leggendo ora), ma per una documentazione più elaborata è
194 una già esistente). Per esempio, il sottosistema grafico è documentato nella
199 Consultate la documentazione di `Sphinx`_ e `reStructuredText`_ per maggiori
203 `costruttori specifici per Sphinx`_.
206 .. _`costruttori specifici per Sphinx`: http://www.sphinx-doc.org/en/stable/markup/index.html
208 Guide linea per la documentazione del kernel
211 In questa sezione troverete alcune linee guida specifiche per la documentazione
227   1. ``=`` con una linea superiore per il titolo del documento::
233   2. ``=`` per i capitoli::
238   3. ``-`` per le sezioni::
243   4. ``~`` per le sottosezioni::
253 * Per inserire blocchi di testo con caratteri a dimensione fissa (codici di
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
265 Per esempio, un prototipo di una funzione:
271 Il dominio C per kernel-doc ha delle funzionalità aggiuntive. Per esempio,
280 Il nome della funzione (per esempio ioctl) rimane nel testo ma il nome del suo
284 Notate che per una funzione non c'è bisogno di usare ``c:func:`` per generarne
295 Il formato ``list-table`` può essere utile per tutte quelle tabelle che non
297 questo genere di tabelle sono illeggibili per chi legge direttamente i file di
310 * auto-span: la cella più a destra viene estesa verso destra per compensare
331 ( ``..`` ) ed i *collegamenti* (per esempio, un riferimento a
385 "documentation/". Per esempio, potete fare riferimento a questo
395 ``doc``. Per esempio::
397     Vedere :doc:`il mio testo per il collegamento <sphinx>`.
404 Per informazioni riguardo ai riferimenti incrociati ai commenti
405 kernel-doc per funzioni o tipi, consultate
413 e ``kernel-image``. Per esempio, per inserire una figura di un'immagine in
428 Le direttive del kernel per figure ed immagini supportano il formato **DOT**,
429 per maggiori informazioni
479 Per la scrittura di codice **SVG**::