z3c.recipe.sphinxdoc Use Sphinx to build documentation for zope.org. z3c.recipe.sphinxdoc ==================== Introduction ------------ This buildout recipe aids in the generation of documentation for the zope.org website from restructured text files located in a package. It uses Sphinx to build static html files which can stand alone as a very nice looking website. Usage Instructions ------------------ Suppose you have a package called ``z3c.form``. In the ``setup.py`` for ``z3c.form`` it is recommended that you add a ``docs`` section to the extras_require argument. It should look something like this:: extras_require = dict( docs = ['Sphinx', 'z3c.recipe.sphinxdoc'] ) Then in the buildout.cfg file for your package, add a ``docs`` section that looks like this:: [docs] recipe = z3c.recipe.sphinxdoc eggs = z3c.form [docs] Be sure to include it in the parts, as in:: [buildout] develop = . parts = docs Now you can rerun buildout. The recipe will have created an executable script in the bin directory called ``docs``. This script will run the Sphinx documentation generation tool on your source code. By default, it expects there to be an ``index.txt`` file in the source code. In this case, ``index.txt`` would have to be in ``src/z3c/form/index.txt``. This file can be a standard restructured text file, and can use all the sphinx goodies. For example, your ``index.txt`` might look like this:: Welcome to z3c.form's documentation! ==================================== Contents: .. toctree:: :maxdepth: 2 README Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` You should read the documentation for Sphinx to learn more about it. It is available here: http://sphinx.pocoo.org/ Now you should be able to run the ``docs`` script:: $ ./bin/docs This generates all the documentation for you and placed it in the parts directory. You can then open it up in firefox and take a look:: $ firefox parts/docs/z3c.form/build/index.html And that's it! ======= CHANGES ======= 0.0.5 (2008-05-11) ------------------ - Initial release. Paul Carduner 2a5d53de05a9e41953ed1826447b07e9a7fa1525 0.0.5