Metadata-Version: 1.0
Name: z3c.recipe.sphinxdoc
Version: 0.0.5
Summary: Use Sphinx to build documentation for zope.org.
Home-page: http://pypi.python.org/pypi/z3c.recipe.sphinxdoc/
Author: Paul Carduner
Author-email: zope-dev@zope.org
License: ZPL 2.1
Description: z3c.recipe.sphinxdoc
        ====================
        
        Introduction
        ------------
        
        This buildout recipe aids in the generation of documentation for the
        zope.org website from restructured text files located in a package.
        It uses Sphinx to build static html files which can stand alone as a
        very nice looking website.
        
        Usage Instructions
        ------------------
        
        Suppose you have a package called ``z3c.form``.  In the ``setup.py``
        for ``z3c.form`` it is recommended that you add a ``docs`` section
        to the extras_require argument.  It should look something like this::
        
        extras_require = dict(
        docs = ['Sphinx',
        'z3c.recipe.sphinxdoc']
        )
        
        Then in the buildout.cfg file for your package, add a ``docs`` section
        that looks like this::
        
        [docs]
        recipe = z3c.recipe.sphinxdoc
        eggs = z3c.form [docs]
        
        Be sure to include it in the parts, as in::
        
        [buildout]
        develop = .
        parts = docs
        
        Now you can rerun buildout.  The recipe will have created an
        executable script in the bin directory called ``docs``.
        
        This script will run the Sphinx documentation generation tool on your
        source code.  By default, it expects there to be an ``index.txt`` file
        in the source code.  In this case, ``index.txt`` would have to be in
        ``src/z3c/form/index.txt``.  This file can be a standard restructured
        text file, and can use all the sphinx goodies.  For example, your
        ``index.txt`` might look like this::
        
        Welcome to z3c.form's documentation!
        ====================================
        
        Contents:
        
        .. toctree::
        :maxdepth: 2
        
        README
        
        Indices and tables
        ==================
        
        * :ref:`genindex`
        * :ref:`modindex`
        * :ref:`search`
        
        You should read the documentation for Sphinx to learn more about it.
        It is available here: http://sphinx.pocoo.org/
        
        Now you should be able to run the ``docs`` script::
        
        $ ./bin/docs
        
        This generates all the documentation for you and placed it in the
        parts directory.  You can then open it up in firefox and take a look::
        
        $ firefox parts/docs/z3c.form/build/index.html
        
        And that's it!
        
        =======
        CHANGES
        =======
        
        0.0.5 (2008-05-11)
        ------------------
        
        - Initial release.
        
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Zope Public License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
