Differences

This shows you the differences between two versions of the page.

--- doc:appunti:software:rst_sphinx [2012/02/10 15:13] – niccolo
+++ doc:appunti:software:rst_sphinx [2012/11/21 10:24] (current) – [Personalizzare lo stile di rst2pdf] niccolo
@@ Line 4: / Line 4: @@
   * [[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.
@@ Line 37: / Line 52: @@
 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>