Metadata-Version: 2.0
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
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
Requires-Dist: Sphinx
Requires-Dist: docutils
Requires-Dist: setuptools
Requires-Dist: zc.buildout
Requires-Dist: zc.recipe.egg
Provides-Extra: test
Requires-Dist: zope.testing; extra == 'test'
Requires-Dist: zope.testrunner; extra == 'test'

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


