====== reStructuredText e Sphinx ======

  * [[http://docutils.sourceforge.net/docs/user/rst/quickref.html|Quick reStructuredText]]
  * [[http://sphinx.pocoo.org/index.html|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 [[http://docs.python.org/|documentazione ufficiale sul sito di Python]] è generata con Sphinx.
===== Installazione =====

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**
===== Preparazione della directory =====

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

<code>
mkdir docs
cd docs
sphinx-quickstart
</code>

Ecco un esempio di come rispondere alle domande:

<code>
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
</code>

===== Personalizzazione del tema =====

Scegliere un tema tra [[http://sphinx.pocoo.org/theming.html|quelli predefiniti]]: ogni stile ha le sue opzioni personalizzabili, vedere la documentazione. L'output HTML può essere controllato da opportune [[http://sphinx.pocoo.org/config.html#options-for-html-output|opzioni]]. Editare quindi il file **''conf.py''**:

<code python>
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'
</code>

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:

<code css>
@import url('default.css');
</code>
===== Aggiunta di un documento =====

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:

<file>
Contents:

.. toctree::
   :maxdepth: 2

   manuale_postgis/manuale_postgis
</file>

Per generare la documentazione HTML si esegue:

<code>
make html
</code>

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:

<code>
make latexpdf
</code>

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

===== Personalizzare lo stile di rst2pdf =====

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

<file>
.. |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|   |
  +------------------------+-----------------+
</file>

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

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

e quindi si crea il PDF:

<code>
rst2pdf -s custom-pdf.style documento.rst
</code>