• Quick reStructuredText
• Sphinx

Il progetto reStructuredText (abbreviato in reST) nasce per la documentazione dei progetti scritti in Python, ma in generale può essere usato come linguaggio di markup per scrivere documentazione. Sphinx invece è un sistema per la generazione della documentazione, in particolare è in grado di trasformare una gerarchia di documenti .rst in una risorsa facilmente navigabile con un browser (make html). La documentazione ufficiale sul sito di Python è generata con Sphinx.

Installare i seguenti pacchetti:

• rst2pdf
• python-docutils
• python-sphinx

Per la generazione completa dell'HTML e di documenti PDF semplici (un file PDF per ogni file .rst) questi pacchetti sono sufficienti. Il sistema Sphinx consente inoltre di generare un file PDF unico a partire dalla directory radice, in tal caso bisogna installare anche:

• texlive-latex-recommended
• texlive-latex-extra
• texlive-fonts-recommended

Creare una directory che sarà la radice di tutta la documentazione. Ogni documento potrà essere messo nella sua sottodirectory.

mkdir docs
cd docs
sphinx-quickstart

Ecco un esempio di come rispondere alle domande:

Root path for the documentation [.]
Separate source and build directories (y/N) [n]
Name prefix for templates and static dir [_]
Project name: Rigacci.Org
Author name(s): Rigacci.Org
Project version: 1
Project release [1]: 1.0
Source file suffix [.rst]
Name of your master document (without suffix) [index]
Do you want to use the epub builder (y/N) [n]
autodoc: automatically insert docstrings from modules (y/N) [n]
doctest: automatically test code snippets in doctest blocks (y/N) [n]
intersphinx: link between Sphinx documentation of different projects (y/N) [n]
todo: write "todo" entries that can be shown or hidden on build (y/N) [n]: y
coverage: checks for documentation coverage (y/N) [n]
pngmath: include math, rendered as PNG images (y/N) [n]
mathjax: include math, rendered in the browser by MathJax (y/N) [n]: y
ifconfig: conditional inclusion of content based on config values (y/N) [n]
viewcode: include links to the source code of documented Python objects (y/N) [n]
Create Makefile? (Y/n) [y]
Create Windows command file? (Y/n) [y]: n

Scegliere un tema tra quelli predefiniti: ogni stile ha le sue opzioni personalizzabili, vedere la documentazione. L'output HTML può essere controllato da opportune opzioni. Editare quindi il file conf.py:

html_theme = 'default'
 
html_theme_options = {
    'sidebarbgcolor':   "#40a52b", # Verde chiaro Faunalia
    'sidebarlinkcolor': "#222222", # Grigio molto scuro
    'footerbgcolor':    "#e7e1de", # Grigio chiaro Faunalia
    'footertextcolor':  "#444444", # Grigio scuro Faunalia
    'relbarbgcolor':    "#317f21"  # Verde scuro Faunalia
}
 
# Custom CSS: if you want just redefine some styles, use @import url('default.css').
#html_style = 'html_faunalia.css'
 
html_logo = 'logo_faunalia.png'
html_favicon = 'favicon_faunalia.ico'

I file logo_faunalia.png e favicon_faunalia.ico possono stare nella directory radice (verranno copiati in _build/html/_static/ durante il build). Il foglio di stile personalizzato deve essere messo in _static/, come prima istruzione carica il foglio di stile predefinito:

@import url('default.css');

Si crea una sottodirectory, ad esempio manuale_postgis, dentro la quale si mette il documento, es. manuale_postgis.rst, le immagini, ecc.

Nel file index.rst si aggiunge un riferimento al documento:

Contents:

.. toctree::
   :maxdepth: 2

   manuale_postgis/manuale_postgis

Per generare la documentazione HTML si esegue:

make html

Il risultato viene creato in _build/html/ e può essere direttamente pubblicato sul web.

Per generare il PDF complessivo di tutti i documenti si esegue:

make latexpdf

In questo caso lo stile non è dei migliori, secondo me è preferibile quello utilizzato da rst2pdf (che però agisce sul singolo documento .rst).

Ad esempio vogliamo creare una tabella per header e footer, senza bordo. Il documento.rst conterrà:

.. |rigacci_org| image:: images/picture_0.png
   :width: 1.5cm
   :alt: Rigacci.Org

.. |cc-by-nc-sa| image:: images/picture_2.png
   :width: 1.2cm
   :alt: cc-by-nc-sa

.. header::

  .. class:: headertable

  +---------------+--------------------------------------------+
  |               |.. class:: centered                         |
  |               |                                            |
  | |rigacci_org| | PostgreSQL/PostGIS: il geodatabase libero  |
  +---------------+--------------------------------------------+

.. footer::

  .. class:: headertable

  +------------------------+-----------------+
  |                        |.. class:: right |
  |                        |                 |
  | ###Page###/###Total### | |cc-by-nc-sa|   |
  +------------------------+-----------------+

Si crea un foglio di stile custom-pdf.style con:

styles:
    headertable:
        parent: table
        commands: []
            [VALIGN, [ 0, 0 ], [ -1, -1 ], CENTER ]
            [ROWBACKGROUNDS, [0, 0], [-1, -1], [white,#E0E0E0]]

e quindi si crea il PDF:

rst2pdf -s custom-pdf.style documento.rst