.. _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/