Metadata-Version: 1.1
Name: z3c.recipe.sphinxdoc
Version: 1.1.0
Summary: Use Sphinx to build documentation for zope.org.
Home-page: https://github.com/zopefoundation/z3c.recipe.sphinxdoc/
Author: Paul Carduner, Zope Foundation and Contributors
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.rst`` file
        in the source code.  In this case, ``index.rst`` would have to be in
        ``src/z3c/form/index.rst``.  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
        
        Additional Options
        ==================
        
        By default, this recipe generates documentation that looks like the
        new zope website ( http://new.zope.org ) by overriding the default
        layout template and css file used by sphinx.  You can modify this
        behavior with options in your buildout configuration.
        
        Give me back Sphinx's default look!
        -----------------------------------
        
        To get back the default look of sphinx, you could use a configuration
        like this::
        
          [docs]
          recipe = z3c.recipe.sphinxdoc
          eggs = z3c.form [docs]
          default.css =
          layout.html =
        
        I want my own custom look
        -------------------------
        
        You can also specify your own layout template and css like so::
        
          [docs]
          recipe = z3c.recipe.sphinxdoc
          eggs = z3c.form [docs]
          default.css = http://my.own.website.com/mystyles/some-theme.css
          layout.html = /path/to/layout.html
        
        Note that you can either specify a path on the local file system or a
        url to an external css file.
        
        Use sphinx extension modules
        ----------------------------
        
        Sphinx provides a set of extensions, for example ``sphinx.ext.autodoc``
        or ``sphinx.ext.doctest``. To use such an extension change your
        configuration like::
        
          [docs]
          recipe = z3c.recipe.sphinxdoc
          eggs = z3c.form [docs]
          extensions = sphinx.ext.autodoc sphinx.ext.doctest
        
        Arbitrary Configuration
        -----------------------
        
        Sphinx and its extensions offer many configuration options. You can
        specify any of those by using the ``extra-conf`` option. This option
        takes a sequence of lines that are simply inserted into the generated
        ``conf.py``. Anything you specify here will override other settings
        this recipe established (just watch your leading line indentation)::
        
          [docs]
          recipe = z3c.recipe.sphinxdoc
          eggs = z3c.form [docs]
          extensions = sphinx.ext.autodoc
                       sphinx.ext.todo
                       sphinx.ext.viewcode
                       sphinx.ext.intersphinx
                       repoze.sphinx.autointerface
                       sphinxcontrib.programoutput
          default.css =
          layout.html =
          extra-conf =
                   autodoc_default_flags = ['members', 'show-inheritance',]
                   autoclass_content = 'both'
                   intersphinx_mapping = {
                   'python':  ('http://docs.python.org/2.7/', None),
                   'boto': ('http://boto.readthedocs.org/en/latest/', None),
                   'gunicorn': ('http://docs.gunicorn.org/en/latest/', None),
                   'pyquery': ('http://packages.python.org/pyquery/', None) }
                   intersphinx_cache_limit = -1
                   todo_include_todos = True
        
                   # The suffix of source filenames. Override back to txt.
                   source_suffix = '.txt'
        
                   # Choose an entire theme. Note that we disabled layout.html
                   # and default.css.
                   html_theme = 'classic'
        
        
        =========
         CHANGES
        =========
        
        1.1.0 (2017-07-05)
        ==================
        
        - Add support for Python 3.4, 3.5 and 3.6 and PyPy.
        
        - Remove support for Python 2.6 and 3.3.
        
        - Change the default source suffix from ``.txt`` to ``.rst``. You can
          override this using the new ``extra-conf`` setting.
        
        - Add the ability to specify arbitrary configuration in the
          ``extra-conf`` setting. This is useful for things like configuring
          extensions, overriding the defaults set by this recipe, and
          configuring a sphinx theme.
        
        - Stop forcing a value of ``default.css`` for ``html_style`` even when
          the ``default.css`` setting is configured to an empty value. This
          makes it possible to use ``html_theme`` to set a sphinx theme, and
          it properly lets the default Sphinx theme be used (by setting both
          ``default.css`` and ``layout.html`` to empty values).
        
        - Ignore bad eggs in the documentation working set. Previously they
          would raise internal errors without any explanation. Now, they log a
          warning pinpointing the bad egg. Fixes `issue 6
          <https://github.com/zopefoundation/z3c.recipe.sphinxdoc/issues/6>`_.
        
        
        1.0.0 (2013-02-23)
        ==================
        
        - Added Python 3.3 support.
        
        - Bug: fix layout directory if layout is overriden by user
        
        0.0.8 (2009-05-01)
        ==================
        
        - Feature: Added new option `doc-eggs` which specifies the list of eggs for
          which to create documentation explicitely.
        
        - Feature: Changed building behavior so that the documentation for each
          package is built in its own sub-directory.
        
        - Feature: Added new option `extensions` which takes a whitespace
          separated list of sphinx extension modules. This extensions can be
          used to build the documentation.
        
        0.0.7 (2009-02-15)
        ==================
        
        - Bug: fix python 2.4 support
        
        - Bug: fix broken srcDir path generation for windows
        
        0.0.6 (2009-01-19)
        ==================
        
        - Feature: Allow you to specify a url or local file path to your own
          default.css and layout.html files.
        
        0.0.5 (2008-05-11)
        ==================
        
        - Initial release.
        
Keywords: buildout sphinx docs recipe
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Zope Public License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Framework :: Buildout
