Metadata-Version: 1.0
Name: collective.recipe.sphinxbuilder
Version: 0.6.3.2
Summary: ZC.buildout recipe to generate and build Sphinx-based documentation in the buildout.
Home-page: http://svn.plone.org/svn/collective/buildout/collective.recipe.sphinxbuilder/trunk
Author: Tarek Ziade
Author-email: tarek@ziade.org
License: ZPL
Description: .. 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.
        
        
        =======
        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 `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.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].
        
        
Keywords: buildout sphinx
Platform: UNKNOWN
Classifier: Framework :: Buildout
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: Zope Public License
