Merge pull request #7 from zopefoundation/extra-conf

Support extra configuration settings. Fixes #3

CHANGES.rst

@@ -9,7 +9,13 @@
 
 - Remove support for Python 2.6 and 3.3.
 
-- Change the default source suffix from ``.txt`` to ``.rst``.
+- 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.
 
 
 1.0.0 (2013-02-23)

src/z3c/recipe/sphinxdoc/__init__.py

@@ -42,6 +42,7 @@
 html_static_path = ['%(staticDir)s']
 html_last_updated_fmt = '%%b %%d, %%Y'
 extensions = %(extensions)r
+%(extra_conf)s
 """
 
 class ZopeOrgSetup(object):
@@ -129,7 +130,8 @@ def install(self):
                     staticDir=staticDir,
                     templatesDir=templatesDir,
                     indexDoc=self.options.get('index-doc','index'),
-                    extensions=self.options.get('extensions','').split()
+                    extensions=self.options.get('extensions','').split(),
+                    extra_conf=self.options.get('extra-conf', ''),
                     )
                 )
 
@@ -162,7 +164,7 @@ def install(self):
             self.buildout['buildout']['bin-directory'],
             extra_paths=self.egg.extra_paths,
             arguments = "%r" % projectsData,
-            ))
+        ))
 
         return installed
 

src/z3c/recipe/sphinxdoc/index.rst

@@ -78,7 +78,7 @@ Additional Options
 ==================
 
 By default, this recipe generates documentation that looks like the
-new zope website ( http://new.zope.org ) by ovveriding the default
+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.
 
@@ -111,11 +111,49 @@ 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
+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'

src/z3c/recipe/sphinxdoc/tests/test_sphinxdoc.py

@@ -14,6 +14,7 @@
 
 import shutil
 import subprocess
+import sys
 import tempfile
 import os
 import unittest
@@ -65,6 +66,18 @@ def templates_path(self):
     def static_path(self):
         return os.path.join(self.part_path, '.static')
 
+    def _check_conf_py_can_be_evald(self):
+        args = [sys.executable,
+                '-c',
+                'import sys; sys.path.insert(0, "%s"); import conf' % self.part_path]
+        subprocess.check_call(args)
+
+    def _read_conf_file(self):
+        conf_path = os.path.join(self.part_path, 'conf.py')
+        with open(conf_path, 'r') as f:
+            conf = f.read()
+        return conf
+
     def test_construct_sets_script(self):
         docs, buildout = self._makeOne()
         self.assertEqual(docs.options['script'],
@@ -78,9 +91,8 @@ def test_openfile_falls_to_url(self):
     def test_basic_install(self):
         docs, _ = self._makeOne()
         docs.install()
-        conf_path = os.path.join(self.part_path, 'conf.py')
-        with open(conf_path, 'r') as f:
-            conf = f.read()
+        self._check_conf_py_can_be_evald()
+        conf = self._read_conf_file()
 
         self.assertIn(os.path.abspath(self.templates_path), conf)
         self.assertIn(os.path.abspath(self.static_path), conf)
@@ -122,3 +134,23 @@ def test_override_layout(self):
         with open(html_path, 'r') as f:
             html = f.read()
             self.assertEqual(html, '')
+
+    def test_extra_conf(self):
+        import textwrap
+        docs, _ = self._makeOne(options={
+            'extra-conf': textwrap.dedent("""\
+            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
+            """
+            )
+        })
+        docs.install()
+        self._check_conf_py_can_be_evald()
+        conf = self._read_conf_file()
+        self.assertIn('intersphinx_mapping', conf)