Introduzione

Nell'ambito di attività di sviluppo software, desktop o web, la richiesta da parte del Committente include sempre la stesura di un manuale utente che deve svilupparsi e aggiornasri parallelamente al software stesso. In più di un'occasione ci siamo affidati a comuni strumenti di editing testuale per arrivare a fornire al Cliente il classico PDF arrichito di immagini e, nei migliori dei casi, di link a video tutorial. Sebbene questa ci sembrasse la via più semplice e comoda anche per il Cliente, non c'è voluto molto tempo per rendersi conto dei limiti di questa soluzione. Il primo fra tutti la difficoltà di mantenere costantemente aggiornato il manuale e, non meno importante, la gestione delle diverse versioni e, in alcuni casi particolari, della traduzione multilingua. In quanti di noi ci siamo ritrovati a nominare l'ennesimo file con il suffisso _versione_N, con il rischio di non partire mai dall'ultima creata o di perdere pezzi tra una versione e l'altra o, nei casi più critici, di perdere o danneggiare interi file. Proprio per fare fronte a queste criticità, che per un'azienda si traducono il più delle vote in una considerevole perdita di tempo, negli anni ci siamo evoluti e abbiamo iniziato a volgere lo sguardo verso strumenti più efficaci per noi e che, allo stesso tempo, mantenessero la semplicità di consultazione da parte dell'utente. In questo approfondimento quindi proponiamo la soluzione che abbiamo deciso di adottare per la manualistica: l'uso combinato di Sphinx e ReadTheDocs.

Strumenti

Sphinx, è un documentation generator in grado di trasformare semplici file di testo in una risorsa facilmente navigabile da browser grazie alla presenza di riferimenti incrociati, indici, tool di ricerca, ecc. Inoltre consente di generare il proprio manuale in diversi formati (PDF, EPUB, HTML, LaTex, ecc.), di aggiungere immagini, gif animate, video e collegamenti diretti a piattaforme per la condivisione di contenuti multimediali (es. Vimeo e Youtube). Sphinx usa il reStructuredText come linguaggio di markup.

Sphinx può essere installato su un proprio server, oppure è possibile appoggiarsi a alla piattaforma Open Source ReadTheDocs per l'hosting dei propri manuali.

La piattaforma di hosting ReadTheDocs è assolutamente gratuita per la manualistica di progetti Open Source, è sufficiente creare il proprio account sulla piattaforma o loggarsi direttamente con il proprio utente GitHub, GitLab o Bitbucket.\ I vantaggi di ReadTheDocs, per chi redige e gestisce il manuale sono diversi:

• puoi creare un progetto ReadTheDocs direttamente collegato alla repository GitHub, GitLab o Bitbucket che contiene il codice del manuale
• la piattaforma compila il manuale per te, puoi dimenticarti di Sphinx e dei comandi da terminale che dovresti lanciare ogni volta che apporti modifiche al tuo manuale. In questo modo, il codice contenuto nella repository e la pgina web del manuale saranno sempre sincronizzati
• puoi gestire le diverse versioni del tuo manuale

• con un po' di lavoro in più sui file di configurazione, puoi personalizzare il template del tuo manuale aggiungendo loghi, cambiando colori e impaginazione

  Ma come inizializzare la repository che conterrà il tuo prossimo manuale?

  Il primo passo da fare verso la pubblicazione del manuale, è la creazione di una repsoitory GitHub, GitLab o Bitbucket dedicata e pubblica. La repository deve contenere:

• il file di configurazione di Sphinx conf.py da modificare secondo le proprie esigenze ( un esmpio si trova qui )
• il file index.rst con l'indice del manuale scritto in reStructuredText

IL TITOLO DEL MANUALE
======================
Contenuti
.. toctree::
  intro
  pagina_1
  pagina_2
  pagina_x

Dove intro, pagina_1, pagina_2 e tutte le voci elencate sotto l'elemento toctree sono i nomi dei vari file .rst che costituiscono le pagine del manuale.

Solo con questi due file, è possibile accedere alla piattaforma ReadTheDocs e creare il proprio progetto seguendo questi pochi e semplici step:

• accedere a ReadTheDocs e loggarsi con il proprio utente GitHub, GitLab o Bitbucket a seconda di dove è stata creata la repository che contiene il manuale
• andare in I miei progetti
• tasto Importa un progetto e selezionare la repository creata ad hoc per il manuale
• definire eventuali impostazioni (Amministrazione)

• compilare la versione

  Al termine della compilazione, cliccando su Mostra documenti, sarà possibile visualizzare su web una prima bozza del manuale!

Un esempio di repository GitHub con una struttura minimale di manuale realizzato per la compilazione su ReadTheDocs è disponibile qui

La sintassi reStructuredText

Ora che la struttura del manuale è pronta, non resta che inserire i contenuti. Come accennato, il linguaggio con cui scrivere il manuale è il reStructuredText. La sintassi non è complicata, soprattutto se si ha già un po' di dimestichezza con il markdown, ma all'inizio può essere un po' difficile da "digerire". Online si trova moltissima documentazione, ma è sempre utile sapere dove trovare qualche esempio soprattutto per elementi di base come grassetto, corsivo, a capo, liste, liste numerate, ecc.\ Ecco quindi una carrellata di esempi di sintassi reStructuredText per arricchire il manuale e renderlo ancora più semplice e comprensibile per gli utenti finali.

Suddivisione della pagina e "segnalibri"

  ..
    questo è un titolo

Introduzione
==================

..
    questa è una sezione

Credits
------------------

..
    questa è una sotto-sezione

Subsection
+++++++++++++++++++

..
    aggiungere un link a una sezione della pagina, sotto la sintassi del link (:ref:`section-anchor`) è necessario poi aggiungere la riga (.. _section-anchor:) nel punto in cui si vuole puntare il link

Example of anchor to a section :ref:`section-anchor`

.. _section-anchor:
Sezione
------------------

Commenti

..
    questo è un commento

Evidenziazione testi

Testo in **Grassetto** *Italico* |examplesuperscript| |examplesubscript|

.. |examplesuperscript| replace:: example\ :sup:`superscript`\

.. |examplesubscript| replace:: example\ :sub:`subscript`\

..
    aggiungere una box di note

.. note:: Example of note box.

..
    aggiungere una box "Vedi anche"

.. seealso:: Example of seealso box.

..
    aggiungere una box di warning

.. warning:: Example of warning box.

..
    aggiungere una box di suggerimento

.. hint:: Example of hint box.

Immagini, Link e riferimenti esterni

..
    aggiungere un'immagine

.. image:: img/Gter.png

..
    aggiungere un'immagine centrata

.. image:: img/Gter.png
  :align: center

..
    link

This is a link to a web page https://www.gter.it/.

..
    link con alias

This is a link to a `web page. <https://www.gter.it/>`__

..
    aggiungere codice html (es. iframe)

Esempio di iframe html

.. raw:: html

    <div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; max-width: 100%; height: auto;">
        <iframe src="https://www.gter.it/" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture in-picture" allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe>
    </div>

Snippet di codice

..
  aggiungere un blocco di codcie (es. html)

.. code-block:: html

  <b><a href="https://www.gter.it/">link</a></b> - Esempio di code-block.

Liste

Esempio di lista puntata:

* item 1
* item 2
* item 3
* etc.

Esempio di lista numerata:

#. item 1
#. item 2
#. item 3

La resa su ReadTheDocs degli esempi sopra, si può vedere a questo link