collective.recipe.sphinxbuilder 0.7.1

.. contents::

- Code repository: https://github.com/sdouche/collective.recipe.sphinxbuilder
- Documentation: http:/docs.garbas.si/collective.recipe.sphinxbuilder
- Questions and comments to tarek_at_ziade.org, rok_at_garbas.si, sdouche_at_sdouche.com


Detailed Documentation
**********************

===============
What is Sphinx?
===============

Sphinx is the mainly 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 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, PDF or even
epub.

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.


=======
Plone 4
=======

Usage with Plone 4 is even easier::

[buildout]
parts =
...
sphinxbuilder
...

[sphinxbuilder]
recipe = collective.recipe.sphinxbuilder
interpreter = ${buildout:directory}/bin/zopepy

Follow quick-start tutorial and do not forget to add interpreter with
installed eggs to access your sourcecode with Sphinx.

=================
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 `doctest`, `html`, `latex`, `pdf` or `epub`.

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 ...src/collective/recipe/sphinxbuilder/docs /sample-buildout/docs/html
...

If we want `latex`, 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)
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

Finally 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...
Making output directory...
<BLANKLINE>

If we want `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

We will skip running the script in tests, because the PDF builder depends
on libraries which may not be installed.

If we want `epub`, 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)
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 epub

We 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)
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 doctest
make html

Again, we will skip running them, this time to avoid a recursive fork bomb. ;)

If we want `extra-paths`, we can define them as normal paths or as unix
wildcards (see `fnmatch` module) ::
>>> 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)
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..
Generated script '/sample-buildout/bin/sphinx-quickstart'.
Generated script '/sample-buildout/bin/sphinx-build'.
<BLANKLINE>

============
Contributors
============

* Tarek Ziade, original author
* Rok Garbas
* Sidnei da Silva
* Hans-Peter Locher
* Domen Kozar
* Tres Seaver
* Sébastien Douche, maintainer

=======
Changes
=======

0.7.1 (2012-04-29):
===================

- Add the epub output.
- Fixed tests:
- Use required package versions during tests
- Use standard `doctest` instead of `zope.testing.doctest`.

0.7.0 (2010-09-10):
===================

- requires Sphinx >= 1.0

0.6.3.3 (2010-07-15)
==========================

- added `doctest` option to recipe's `output` options (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].