collective.recipe.sphinxbuilder ZC.buildout recipe to generate and build Sphinx-based documentation in the buildout. .. contents:: - Code repository: https://svn.plone.org/svn/collective/buildout/collective.recipe.sphinxbuilder - Documentation: http:/docs.garbas.si/collective.recipe.sphinxbuilder - Questions and comments to tarek_at_ziade.org, rok_at_garbas.si Detailed Documentation ********************** ================ What is Sphinx ? ================ Sphinx is the rising tool in the Python community to build documentation. See http://sphinx.pocoo.org. It is now used for instance by Python. See http://docs.python.org/dev and many others Sphinx uses reStructuredText, and can be used to write your buildout-based application. This recipe sets everything up for you, so you can provide a nice-looking documentation within your buildout, in static html or even PDF. The fact that your documentation is managed like your code makes it easy to maintain and change it. =========== Quick start =========== To use the recipe, add in your buildout configuration file a section like this:: [buildout] parts = ... sphinxbuilder ... [sphinxbuilder] recipe = collective.recipe.sphinxbuilder source = ${buildout:directory}/docs-source build = ${buildout:directory}/docs Run your buildout and you will get a few new scripts in the `bin` folder, called: - `sphinx-quickstart`, to quickstart sphinx documentation - `sphinxbuilder`, script that will To quickstart a documentation project run, as you would normaly do with Sphinx:: $ bin/sphinx-quickstart and anwser few questions and choose `docs-source` as you source folder. To build your documentation, just run the sphinx script:: $ bin/sphinxbuilder That's it ! You will get a shiny Sphinx documenation in `docs/html`. Write your documentation, go in `docs-source`. Everytime source is modified, `sphinxbuilder` run script again. A good starting point to write your documentation is: http://sphinx.pocoo.org/contents.html. ================= Supported options ================= The recipe supports the following options: build (default: `docs`) Specify the build documentation root. source (default: `{build-directory}/source`) Speficy the source directory of documentation. outputs (default: `html`) Multiple-line value that defines what kind of output to produce. Can be `html`, `latex` or `pdf`. script-name (default: name of buildout section) The name of the script generated interpreter Path to python interpreter to use when invoking sphinx-builder. extra-paths Extra paths to be inserted into sys.path. products Extra product directories to be extend the Products namespace for old-style Zope Products. ============= Example usage ============= The recipe can be used without any options. We'll start by creating a buildout that uses the recipe:: >>> write('buildout.cfg', ... """ ... [buildout] ... parts = sphinxbuilder ... ... [sphinxbuilder] ... recipe = collective.recipe.sphinxbuilder ... source = collective.recipe.sphinxbuilder:docs ... """) Let's run the buildout:: >>> print 'start', system(buildout) start Installing sphinxbuilder. collective.recipe.sphinxbuilder: writing MAKEFILE.. collective.recipe.sphinxbuilder: writing BATCHFILE.. collective.recipe.sphinxbuilder: writing custom sphinx-builder script.. Generated script '/sample-buildout/bin/sphinx-quickstart'. Generated script '/sample-buildout/bin/sphinx-build'. <BLANKLINE> What are we expecting ? A `docs` folder with a Sphinx structure:: >>> docs = join(sample_buildout, 'docs') >>> ls(docs) - Makefile - make.bat A script in the `bin` folder to build the docs:: >>> bin = join(sample_buildout, 'bin') >>> ls(bin) - buildout - sphinx-build - sphinx-quickstart - sphinxbuilder The content of the script is a simple shell script:: >>> script = join(sample_buildout, 'bin', 'sphinxbuilder') >>> print open(script).read() cd ...docs make html >>> print 'start', system(script) start /sample-buildout/bin/sphinx-build -b html -d /sample-buildout/docs/doctrees /home/rok/Projects/collective.recipe.sphinxbuilder/src/collective/recipe/sphinxbuilder/docs /sample-buildout/docs/html ... If we want `latex` and `pdf`, we need to explicitly define it:: >>> write('buildout.cfg', ... """ ... [buildout] ... parts = sphinxbuilder ... ... [sphinxbuilder] ... recipe = collective.recipe.sphinxbuilder ... source = collective.recipe.sphinxbuilder:docs ... outputs = ... html ... latex ... pdf ... """) >>> print 'start', system(buildout) start Uninstalling sphinxbuilder. Installing sphinxbuilder. collective.recipe.sphinxbuilder: writing MAKEFILE.. collective.recipe.sphinxbuilder: writing BATCHFILE.. collective.recipe.sphinxbuilder: writing custom sphinx-builder script.. <BLANKLINE> Let's see our script now:: >>> cat(script) cd ...docs make html make latex cd /sample-buildout/docs/latex && make all-pdf Finally let's run it:: >>> print 'start', system(script) start /sample-buildout/bin/sphinx-build -b html -d /sample-buildout/docs/doctrees /home/rok/Projects/collective.recipe.sphinxbuilder/src/collective/recipe/sphinxbuilder/docs /sample-buildout/docs/html ... Transcript written in ... <BLANKLINE> ============ Contributors ============ * Tarek Ziade, Author * Rok Garbas, likes mandarines * Sidnei da Silva * Hans-Peter Locher, aka mr_savage * Domen Kozar, aka iElectric ======= Changes ======= 0.6.3 (2009-09-09) ================== - update to Sphinx 0.6.3 [garbas] - simplify sphinxbuilder [garbas] - update documentation [garbas] - interpreter options [iElectric] - added logging [iElectric] 0.5.0 (2008-12-06) ================== - Making it compatible with latest sphinx 0.5 [Rok Garbas] - Allow for specifying 'product_directories' in order to be able to document old-style Zope Products. [Sidnei] 0.2.1 (2008-11-18) ================== - Manifest file fixed and making fix release [Rok Garbas] 0.2.0 (2008-11-11) ================== - source tree generated every time under parts/<buildout-section-name> [Rok Garbas] - finds conf options, source, static and template files using entry_point 'collective.recipe.sphinxbuilder' [Rok Garbas] - custom source folder at docs/source [Rok Garbas] - build section moved to docs/html, docs/latex [Rok Garbas] 0.1.1 (2008-09-11) ================== - Using a sphinx-build local to the environment [Tarek] 0.1.0 (2008-09-10) ================== - Initial implementation [Tarek Ziade] - Created recipe with ZopeSkel [Tarek Ziade]. Tarek Ziade 67bd6d2021d55d449b5fda4786eba83a834671f3 0.6.3.1