=============
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>

