• Quick reStructuredText
• Sphinx

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, editare il file conf.py. Ogni stile ha le sue opzioni personalizzabili, vedere la documentazione. L'output HTML può essere controllato da opportune opzioni:

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).

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

Contents:

.. toctree::
   :maxdepth: 2

   manuale_postgis/manuale_postgis

make html