Scarica il codice sorgente: restructuredtext.rst
RST (Restructured Text) è un formato di file inizialmente creato dalla comunità Python per la documentazione (per questo motivo appartiene a Docutils).
I file RST sono semplici file di testo con una sintassi leggera (in confronto all'HTML).
Per usare Restructured Text, sarà necessario installare Python ed il pacchetto docutils.
docutils può essere installato da riga di comando:
$ easy_install docutils
Oppure, se hai pip installato sul tuo sistema:
$ pip install docutils
Ecco un semplice esempio della sintassi RST:
.. Le righe che iniziano con due punti sono comandi speciali. Ma se non è possibile trovare alcun comando, la riga viene considerata come un commento
===============================================================================
I titoli principali sono scritti utilizzando caratteri di uguale, sopra e sotto
===============================================================================
Si noti che devono esserci tanti caratteri di uguale quanti caratteri del titolo.
Anche i titoli normali usano caratteri di uguale, ma solo sotto
===============================================================
I sottotitoli usano i trattini
------------------------------
E i sotto-sottotitoli le tildi
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Puoi inserire il testo in *corsivo* o in **grassetto**, puoi "contrassegnare" il testo come codice con un doppio apice ``: `` print () ``.
Le liste sono semplici come in Markdown:
- primo articolo
- Secondo elemento
- Sottoelemento
oppure
* Primo elemento
* Secondo elemento
* Sottoelemento
Le tabelle sono molto semplici da inserire:
=========== ========
Stato Capitale
=========== ========
Francia Parigi
Giappone Tokio
=========== ========
Anche le tabelle più complesse possono essere inserite facilmente (colonne e/o righe unite) ma ti suggerisco di leggere la documentazione completa per questo :)
Esistono diversi modi per creare collegamenti:
- Aggiungendo un underscore dopo una parola: GitHub_ e aggiungendo l'URL di destinazione dopo il testo (questo metodo ha il vantaggio di non inserire URL non necessari all'interno del testo leggibile).
- Digitando un URL completo: https://github.com/ (verrà automaticamente convertito in un collegamento)
- Utilizzando una sintassi simile a Markdown: `GitHub <https://github.com/>`_ .
.. _GitHub https://github.com/
RST viene fornito con docutils, che dispone di rst2html, per esempio:
$ rst2html miofile.rst output.html
Nota : In alcuni sistemi il comando potrebbe essere rst2html.py
Ma ci sono applicazioni più complesse che utilizzano il formato RST:
Hai un suggerimento? Oppure una correzione? Apri un issue sul GitHub, o fa un pull request da solo!
In origine contribuita da DamienVGN, e modificata da 3 contributore(i).