doc:appunti:software:rst_sphinx
Differences
This shows you the differences between two versions of the page.
Next revision | Previous revision | ||
doc:appunti:software:rst_sphinx [2012/02/10 14:10] – created niccolo | doc:appunti:software:rst_sphinx [2012/11/21 09:24] (current) – [Personalizzare lo stile di rst2pdf] niccolo | ||
---|---|---|---|
Line 3: | Line 3: | ||
* [[http:// | * [[http:// | ||
* [[http:// | * [[http:// | ||
+ | |||
+ | 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, | ||
+ | ===== Installazione ===== | ||
+ | |||
+ | Installare i seguenti pacchetti: | ||
+ | |||
+ | * **rst2pdf** | ||
+ | * **python-docutils** | ||
+ | * **python-sphinx** | ||
+ | |||
+ | Per la generazione completa dell' | ||
+ | |||
+ | * **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. | ||
+ | |||
+ | < | ||
+ | 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: | ||
+ | todo: write " | ||
+ | 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 | ||
+ | </ | ||
+ | |||
+ | ===== Personalizzazione del tema ===== | ||
+ | |||
+ | Scegliere un tema tra [[http:// | ||
+ | |||
+ | <code python> | ||
+ | html_theme = ' | ||
+ | |||
+ | html_theme_options = { | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | } | ||
+ | |||
+ | # Custom CSS: if you want just redefine some styles, use @import url(' | ||
+ | #html_style = ' | ||
+ | |||
+ | html_logo = ' | ||
+ | html_favicon = ' | ||
+ | </ | ||
+ | |||
+ | I file '' | ||
+ | |||
+ | <code css> | ||
+ | @import url(' | ||
+ | </ | ||
+ | ===== Aggiunta di un documento ===== | ||
+ | |||
+ | Si crea una sottodirectory, | ||
+ | |||
+ | Nel file **'' | ||
+ | |||
+ | < | ||
+ | Contents: | ||
+ | |||
+ | .. toctree:: | ||
+ | : | ||
+ | |||
+ | | ||
+ | </ | ||
+ | |||
+ | Per generare la documentazione HTML si esegue: | ||
+ | |||
+ | < | ||
+ | make html | ||
+ | </ | ||
+ | |||
+ | Il risultato viene creato in **'' | ||
+ | |||
+ | 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 **'' | ||
+ | |||
+ | ===== Personalizzare lo stile di rst2pdf ===== | ||
+ | |||
+ | Ad esempio vogliamo creare una tabella per header e footer, senza bordo. Il **'' | ||
+ | |||
+ | < | ||
+ | .. |rigacci_org| image:: images/ | ||
+ | : | ||
+ | :alt: Rigacci.Org | ||
+ | |||
+ | .. |cc-by-nc-sa| image:: images/ | ||
+ | : | ||
+ | :alt: cc-by-nc-sa | ||
+ | |||
+ | .. header:: | ||
+ | |||
+ | .. class:: headertable | ||
+ | |||
+ | +---------------+--------------------------------------------+ | ||
+ | | |.. class:: centered | ||
+ | | | ||
+ | | |rigacci_org| | PostgreSQL/ | ||
+ | +---------------+--------------------------------------------+ | ||
+ | |||
+ | .. footer:: | ||
+ | |||
+ | .. class:: headertable | ||
+ | |||
+ | +------------------------+-----------------+ | ||
+ | | |.. class:: right | | ||
+ | | | | | ||
+ | | ### | ||
+ | +------------------------+-----------------+ | ||
+ | </ | ||
+ | |||
+ | Si crea un foglio di stile **'' | ||
+ | |||
+ | < | ||
+ | styles: | ||
+ | headertable: | ||
+ | parent: table | ||
+ | commands: [] | ||
+ | [VALIGN, [ 0, 0 ], [ -1, -1 ], CENTER ] | ||
+ | [ROWBACKGROUNDS, | ||
+ | </ | ||
+ | |||
+ | e quindi si crea il PDF: | ||
+ | |||
+ | < | ||
+ | rst2pdf -s custom-pdf.style documento.rst | ||
+ | </ |
doc/appunti/software/rst_sphinx.1328883012.txt.gz · Last modified: 2012/02/10 14:10 by niccolo