Package: collective.recipe.sphinxbuilder
ContentsDetailed DocumentationWhat is Sphinx?Quick startPlone 4Supported optionsExample usageContributorsChanges1.1 (2018-04-24)1.0 (2016-07-11)0.9 (2016-06-27)0.8.2 (2013-11-28)0.8.1 (2013-11-27)0.8.0 (2013-11-27)0.7.4 (2013-11-15)0.7.3 (2013-02-16)0.7.2 (2012-10-22)0.7.1 (2012-04-29)0.7.0 (2010-09-10)0.6.3.3 (2010-07-15)0.6.3.2 (2010-02-08)0.6.3.1 (2009-09-25)0.6.3 (2009-09-09)0.5.0 (2008-12-06)0.2.1 (2008-11-18)0.2.0 (2008-11-11)0.1.1 (2008-09-11)0.1.0 (2008-09-10)Code repository:https://github.com/reinout/collective.recipe.sphinxbuilder(since June 2016).Documentation:http://collectiverecipesphinxbuilder.readthedocs.io.Questions and comments toReinout van Reestarek_at_ziade.org, rok_at_garbas.si, sdouche_at_sdouche.com.Detailed DocumentationWhat is Sphinx?Sphinx is the mainly tool in the Python community to build documentation. Seehttp://sphinx.pocoo.org.It is now used for instance by Python. Seehttp://docs.python.organd many
othersSphinx 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, PDF or even
epub.The fact that your documentation is managed like your code makes it easy to
maintain and change it.Quick startTo 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}/docsRun your buildout and you will get a few new scripts in thebinfolder,
called:sphinx-quickstart, to quickstart sphinx documentationsphinxbuilder, script that willTo quickstart a documentation project run, as you would normaly do with Sphinx:$ bin/sphinx-quickstartand anwser few questions and choosedocs-sourceas you source folder.To build your documentation, just run the sphinx script:$ bin/sphinxbuilderThat’s it!You will get a shiny Sphinx documenation indocs/html.
Write your documentation, go indocs-source.
Everytime source is modified,sphinxbuilderrun script again.A good starting point to write your documentation is:http://sphinx.pocoo.org/contents.html.Plone 4Usage with Plone 4 is even easier:[buildout]
parts =
    ...
    sphinxbuilder
    ...

[sphinxbuilder]
recipe = collective.recipe.sphinxbuilder
interpreter = ${buildout:directory}/bin/zopepyFollow quick-start tutorial and do not forget to add interpreter with
installed eggs to access your sourcecode with Sphinx.Supported optionsThe 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 bedoctest,html,latex,pdforepub.script-name (default: name of buildout section)The name of the script generatedinterpreterPath to python interpreter to use when invoking sphinx-builder.extra-pathsExtra paths to be inserted into sys.path.productsExtra product directories to be extend the Products namespace for
old-style Zope Products.Example usageThe 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))
... # doctest: +ELLIPSIS
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'.
Generated script '/sample-buildout/bin/sphinx-apidoc'.
Generated script '/sample-buildout/bin/sphinx-autogen'...What are we expecting?Adocsfolder with a Sphinx structure:>>> docs = join(sample_buildout, 'docs')
>>> ls(docs)
- Makefile
-  make.batA script in thebinfolder to build the docs:>>> bin = join(sample_buildout, 'bin')
>>> ls(bin)
- buildout
- sphinx-apidoc
- sphinx-autogen
- sphinx-build
- sphinx-quickstart
- sphinxbuilderThe content of the script is a simple shell script:>>> script = join(sample_buildout, 'bin', 'sphinxbuilder')
>>> print(open(script).read())
#!/bin/bash
cd ...docs
make html

>>> print('start ' + system(script))
start /sample-buildout/bin/sphinx-build -b html -d /sample-buildout/docs/doctrees ...src/collective/recipe/sphinxbuilder/docs /sample-buildout/docs/html
...If we wantlatex, 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
... """)
>>> print('start ' + system(buildout))
... # doctest: +ELLIPSIS
start Uninstalling sphinxbuilder.
Installing sphinxbuilder.
collective.recipe.sphinxbuilder: writing MAKEFILE..
collective.recipe.sphinxbuilder: writing BATCHFILE..
collective.recipe.sphinxbuilder: writing custom sphinx-builder script...Let’s see our script now:>>> cat(script)
#!/bin/bash
cd ...docs
make html
make latexFinally let’s run it:>>> print('start ' + system(script))
start /sample-buildout/bin/sphinx-build -b html -d /sample-buildout/docs/doctrees   .../src/collective/recipe/sphinxbuilder/docs /sample-buildout/docs/html
...
<BLANKLINE>
Build finished. The HTML pages are in /sample-buildout/docs/html.
...
Build finished; the LaTeX files are in /sample-buildout/docs/latex.
Run `make' in that directory to run these through (pdf)latex...
<BLANKLINE>If we wantpdf, 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))
... # doctest: +ELLIPSIS
start Uninstalling sphinxbuilder.
Installing sphinxbuilder.
collective.recipe.sphinxbuilder: writing MAKEFILE..
collective.recipe.sphinxbuilder: writing BATCHFILE..
collective.recipe.sphinxbuilder: writing custom sphinx-builder script...Let’s see our script now:>>> cat(script)
#!/bin/bash
cd ...docs
make html
make latex
cd /sample-buildout/docs/latex && make all-pdfWe will skip running the script in tests, because the PDF builder depends
on libraries which may not be installed.If we wantepub, like 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
...     epub
... """)
>>> print('start ' + system(buildout))
... # doctest: +ELLIPSIS
start Uninstalling sphinxbuilder.
Installing sphinxbuilder.
collective.recipe.sphinxbuilder: writing MAKEFILE..
collective.recipe.sphinxbuilder: writing BATCHFILE..
collective.recipe.sphinxbuilder: writing custom sphinx-builder script...Let’s see our script now:>>> cat(script)
#!/bin/bash
cd ...docs
make html
make epubWe can also have the script run any doctests in the docs while building:>>> write('buildout.cfg',
... """
... [buildout]
... parts = sphinxbuilder
...
... [sphinxbuilder]
... recipe = collective.recipe.sphinxbuilder
... source = collective.recipe.sphinxbuilder:docs
... outputs =
...     doctest
...     html
... """)
>>> print('start ' + system(buildout))
... # doctest: +ELLIPSIS
start Uninstalling sphinxbuilder.
Installing sphinxbuilder.
collective.recipe.sphinxbuilder: writing MAKEFILE..
collective.recipe.sphinxbuilder: writing BATCHFILE..
collective.recipe.sphinxbuilder: writing custom sphinx-builder script...Let’s see our script now:>>> cat(script)
#!/bin/bash
cd ...docs
make doctest
make htmlAgain, we will skip running them, this time to avoid a recursive fork bomb. ;)If we wantextra-paths, we can define them as normal paths or as unix
wildcards (seefnmatchmodule)>>> write('buildout.cfg',
... """
... [buildout]
... parts = sphinxbuilder
...
... [sphinxbuilder]
... recipe = collective.recipe.sphinxbuilder
... source = collective.recipe.sphinxbuilder:docs
... extra-paths =
...     develop-eggs/
...     eggs/*
... """)
>>> print('start ' + system(buildout))
... # doctest: +ELLIPSIS
start Uninstalling sphinxbuilder.
Installing sphinxbuilder.
collective.recipe.sphinxbuilder: writing MAKEFILE..
collective.recipe.sphinxbuilder: writing BATCHFILE..
collective.recipe.sphinxbuilder: writing custom sphinx-builder script..
collective.recipe.sphinxbuilder: inserting extra-paths...ContributorsTarek Ziade, original authorRok GarbasSidnei da SilvaHans-Peter LocherDomen KozarTres SeaverReinout van Rees, maintainerSébastien DoucheChanges1.1 (2018-04-24)Support other shells thanbash. [icemac]1.0 (2016-07-11)Added windows support. [tkhyn]0.9 (2016-06-27)Added automatic testing with travis-ci.org. [reinout]Trying to fix install on python 3. [reinout]Current code location ishttps://github.com/reinout/collective.recipe.sphinxbuilder[reinout]Documentation is now on readthedocs:http://collectiverecipesphinxbuilder.readthedocs.io/[reinout]0.8.2 (2013-11-28)Prevent a warning when installing with python 3 [reinout]0.8.1 (2013-11-27)Add Python 3 classifier0.8.0 (2013-11-27)Added python 3 support [reinout]0.7.4 (2013-11-15)Update to Buildout 2Cleanup the code to make PEP8 tool happy0.7.3 (2013-02-16)Patch sphinx-build script to terminate with sys.exit()Add warnings-html makefile optionInstall sphinx-apidoc and sphinx-autogen scriptsRename all txt files to rst ones0.7.2 (2012-10-22)Requires Sphinx >= 1.10.7.1 (2012-04-29)Add the epub output.Fixed tests:Use required package versions during testsUse standarddoctestinstead ofzope.testing.doctest.0.7.0 (2010-09-10)Requires Sphinx >= 1.00.6.3.3 (2010-07-15)Addeddoctestoption to recipe’soutputoptions (tseaver)Relaxed required version of Sphinx to allow versions later than
0.6.4 (but still less than 0.7dev).0.6.3.2 (2010-02-08)Fixed interpreter options [iElectric]0.6.3.1 (2009-09-25)Problems with previous release [garbas]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].