.. _use-sphinx:

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 :ref:`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
  :file:`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.


.. _`Rest primer`: http://sphinx-doc.org/rest.html#rst-primer
.. _`Sphinx markup constructs`: http://sphinx-doc.org/markup/index.html#sphinxmarkup
.. _`ReST User Reference`: http://docutils.sourceforge.net/docs/user/rst/quickref.html
.. _`cloud_sptheme`: https://pythonhosted.org/cloud_sptheme/
.. _Sphinx: http://sphinx-doc.org/
.. _`bootstrap-sphinx`: https://pypi.python.org/pypi/sphinx-bootstrap-theme/
