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-start 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 inbuildout.cfg
, sectionvpython
as is not a real dependency.