8.1. Struttura del documento¶
I documenti pubblicati su Docs Italia devono essere suddivisi in file
differenti. Il file index.rst
contiene il titolo del documento, un breve
riassunto e l’indice dei contenuti. Il resto del documento è diviso in
capitoli (sezioni di primo livello) che corrispondono ad altrettanti
file.
example
Esempio di file index.rst
Titolo del documento
====================
.. highlights:
Breve testo che riassume il contenuto del documento. Lorem ipsum dolor
sit amet, consectetur adipiscing elit.
.. toctree::
:numbered:
titolo-primo-capitolo
titolo-secondo-capitolo
I file che contengono le diverse sezioni di primo livello devono essere nominati con il titolo del capitolo, sostituendo tutti gli spazi con il trattino e omettendo le particelle grammaticali.
Poiché la strutturazione del repository impatta sugli URL generati, tutti i file devono essere collocati nella radice del repository.
Per documenti particolarmente complessi, che rendono necessaria una ulteriore suddivisione in file, è possibile creare una directory per ogni sezione (usando il titolo della sezione) e replicare la struttura di un documento semplice all’interno di ogni directory.
example
Esempio di struttura di un documento complesso
├── index.rst
├── titolo-primo-capitolo
│ ├── index.rst
│ ├── primo-paragrafo.rst
│ ├── titolo-interessante.rst
│ └── titolo-sezione.rst
├── titolo-secondo-capitolo
│ ├── index.rst
│ ├── nuova-sezione.rst
│ └── titolo-molto-molto-lungo.rst
└── titolo-terzo-capitolo
├── index.rst
├── paragrafo-rivoluzionario.rst
├── paragrafo-tecnologico.rst
└── paragrafo-tradizionale.rst