Documentation

Documentation for Jumbo packages is written with Sphinx . A theme has been created starting cloud_sptheme and adding the header with logo and dropdown menu as in bootstrap-sphinx.

Sphinx is based on ReST (Restructured Text) from the docutils team, but adds a lot of directive that make uit’s use much more powerful and suited for large projects.

ReST User Reference

the user reference from the docutils team

ReST primer

a primer from SPhinx site

Sphinx markup constructs

Sphinx constructs

Package documentation

When creating a package with jmb kick the correct structure is automatically created so that:

jmb-start -t japp jmb.new
cd jmb.new
jmb-go
dj docs

Creates a perfectly working structure for the documentation with menu entry that point to Jumbo project and local docs for:

  • install (if any external software is needed as hylafax server or squid)

  • setup (configurazion SETTINGS and defaults)

  • commands (explanation of commands provided in management/commands

  • models (if needed)

you area supposed to add any documents you consider needed for you package!

Converting an older package

the simpler way to conver an older package is

  • create a new package with the same name and copy the conf.py file.

  • add jmb.sphinx in the environment. I don’t suggest to put it in setup.py but in buildout.cfg, section vpython as is not a real dependency.