Sphinx: uso di immagini in formato svg

Sphinx è un ambiente per scrivere documentazione.

Originariamente sviluppato per documentare i progetti software scritti in Python, nel tempo si è dimostato abbastanza flessibile per poter essere utilizzato non solo per documentare progetti software [1], ma anche per scrivere documentazione dei tipi più svariati.

Il suo punto di forza consiste nel permettere la stesura del testo utilizzando un formato di markup amichevole, quali reStructuredText o Markdown, per poi generare la documentazione con un formato finale in html, o latex, o pdf, o ...

In questo articolo desidero considerare la gestione di immagini da inserire nel documento in stesura.

Chi scrive documentazione, sa bene che, per quanto possibile, è bene utilizzare formati grafici vettoriali. Infatti questi formati possono essere adattati alla dimensione del supporto che visualizza l'immagine, sfruttandone al massimo le caratteristiche fisiche. Quindi su monitor piccoli (smartphone) avremo una immagine piccola, mentre su monitor grandi (laptop, desktop) avremo una immagine grande, senza avere scalettature evidenti.

Invece i formati grafici raster, durante il processo di adattamento dell'immagine alla dimensione del supporto, possono soffrire di evidenti scadimenti della qualità dell'immagine.

Uno dei formati vettoriali più diffusi è il formato svg. Questo è uno dei formati più diffusi perché riconosciuto dallo standard html [2], e di conseguenza gestibile direttamente da tutti i Web browser moderni.

Bene. Come facciamo ad inserire una immagine svg in un nostro documento?

Qui non descrivo come creare un nuovo progetto di documentazione in Sphinx. Chi ha necessità di imparare da zero l'uso di Sphinx può utilizzare questo tutorial.

Diciamo di avere creato un progetto, e che utilizzamo reStructuredText per scrivere la pagina index.rst della nostra documentazione.

In questa pagina vogliamo visualizzare il file immagine.svg. Bene nel punto in cui si vuole inserire l'immagine basta scrivere la direttiva:

.. image:: immagine.svg

partendo dalla colonna 1 [3] del testo e delimitandola con una linea vuota sopra e una sotto.

Dopo di che possiamo generare la documentazione in html usando il comando:

make html

Tutto bello e funzionale. Ma, purtroppo, se si vuole generare la documentazione in formato pdf, la direttiva image usando il file svg dà luogo ad un errore. Questo perché il pdf viene generato passando per il formato latex. E quest'ultimo non supporta in core il formato svg.

L'escamotage [4] più semplice per aggirare questo problema consiste nel creare due immagini. Una in formato svg, e l'altra con un formato raster supportato nativamente da latex, ad esempio il formato png.

Quindi nel nostro caso creiamo le immagini immagine.svg e immagine.png.

Dopo di che usiamo la direttiva come segue:

.. image:: immagine.*

Si noti che abbiamo usato un asterisco invece di indicare l'estensione del file immagine. In tal modo il convertitore per html userà automaticamente il formato svg, mentre quello latex, con il comando:

make latexpdf

userà il formato png.

In alternativa, è possibile usare l'estensione imgconverter; ma, francamente, non la trovo molto utile per i seguenti motivi:

1. non gestisce in latex l'immagine svg, ma ne effettua una trasformazione in formato raster [5];
2. per effettuare la trasformazione predetta utilizza imagemagick, un ambiente di manipolazione immagini a linea di comando; questo ambiente è interessante [6], ma è pur sempre un software aggiuntivo;
3. è necessaria un (piccola) configurazione aggiuntiva al nostro progetto.

Dulcis in fundo: ho provato ad usare l'estensione in questione, e non sono riuscito ad utilizzarla al volo. Andando sempre di fretta, ho preferito smontare il tutto e continuare ad utilizzare il workaround illustrato.

Più interessante è l'accenno alla possibilità di usare sphinxcontrib-svg2pdfconverter, che però non ho avuto il tempo di provare. Vedremo in futuro ...