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:
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:
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