merge with trunk

CHANGES

@@ -24,6 +24,9 @@ Release 1.0 (in development)
 
 * Added single-file HTML builder.
 
+* Added ``autodoc_default_flags`` config value, which can be used
+  to select default flags for all autodoc directives.
+
 * Added ``tab-width`` option to ``literalinclude`` directive.
 
 * The ``html_sidebars`` config value can now contain patterns as
@@ -107,6 +110,9 @@ Release 1.0 (in development)
 Release 0.6.5 (in development)
 ==============================
 
+* In autodoc, allow customizing the signature of an object where
+  the built-in mechanism fails.
+
 * #331: Fix output for enumerated lists with start values in LaTeX.
 
 * Make the ``start-after`` and ``end-before`` options to the

doc/ext/autodoc.rst

@@ -228,6 +228,24 @@ There are also new config values that you can set:
 
    .. versionadded:: 0.6
 
+.. confval:: autodoc_default_flags
+
+   This value is a list of autodoc directive flags that should be automatically
+   applied to all autodoc directives.  The supported flags are ``'members'``,
+   ``'undoc-members'``, ``'inherited-members'`` and ``'show-inheritance'``.
+
+   If you set one of these flags in this config value, you can use a negated
+   form, :samp:`'no-{flag}'`, in an autodoc directive, to disable it once.
+   For example, if ``autodoc_default_flags`` is set to ``['members',
+   'undoc-members']``, and you write a directive like this::
+
+      .. automodule:: foo
+         :no-undoc-members:
+
+   the directive will be interpreted as if only ``:members:`` was given.
+
+   .. versionadded:: 1.0
+
 
 Docstring preprocessing
 -----------------------

doc/ext/autosummary.rst

@@ -97,6 +97,8 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts:
      :confval:`templates_path` to generate the pages for all entries
      listed. See `Customizing templates`_ below.
 
+     .. versionadded:: 1.0
+
 
 :program:`sphinx-autogen` -- generate autodoc stub pages
 --------------------------------------------------------
@@ -142,6 +144,8 @@ also use this new config value:
 Customizing templates
 ---------------------
 
+.. versionadded:: 1.0
+
 You can customize the stub page templates, in a similar way as the HTML Jinja
 templates, see :ref:`templating`. (:class:`~sphinx.application.TemplateBridge`
 is not supported.)

sphinx/ext/autodoc.py

@@ -378,7 +378,12 @@ class Documenter(object):
             args = "(%s)" % self.args
         else:
             # try to introspect the signature
-            args = self.format_args()
+            try:
+                args = self.format_args()
+            except Exception, err:
+                self.directive.warn('error while formatting arguments for '
+                                    '%s: %s' % (self.fullname, err))
+                args = None
 
         retann = self.retann
 
@@ -666,12 +671,7 @@ class Documenter(object):
         self.add_line(u'', '')
 
         # format the object's signature, if any
-        try:
+        sig = self.format_signature()
-            sig = self.format_signature()
-        except Exception, err:
-            self.directive.warn('error while formatting signature for '
-                                '%s: %s' % (self.fullname, err))
-            sig = ''
 
         # generate the directive header and options, if applicable
         self.add_directive_header(sig)
@@ -1098,6 +1098,10 @@ class AutoDirective(Directive):
     # a registry of type -> getattr function
     _special_attrgetters = {}
 
+    # flags that can be given in autodoc_default_flags
+    _default_flags = set(['members', 'undoc-members', 'inherited-members',
+                          'show-inheritance'])
+
     # standard docutils directive settings
     has_content = True
     required_arguments = 1
@@ -1120,6 +1124,14 @@ class AutoDirective(Directive):
         # find out what documenter to call
         objtype = self.name[4:]
         doc_class = self._registry[objtype]
+        # add default flags
+        for flag in self._default_flags:
+            if flag not in doc_class.option_spec:
+                continue
+            negated = self.options.pop('no-' + flag, 'not given') is None
+            if flag in self.env.config.autodoc_default_flags and \
+               not negated:
+                self.options[flag] = None
         # process the options with the selected documenter's option_spec
         self.genopt = Options(assemble_option_dict(
             self.options.items(), doc_class.option_spec))
@@ -1177,6 +1189,7 @@ def setup(app):
 
     app.add_config_value('autoclass_content', 'class', True)
     app.add_config_value('autodoc_member_order', 'alphabetic', True)
+    app.add_config_value('autodoc_default_flags', [], True)
     app.add_event('autodoc-process-docstring')
     app.add_event('autodoc-process-signature')
     app.add_event('autodoc-skip-member')

sphinx/quickstart.py

@@ -446,7 +446,9 @@ BATCHFILE = '''\
 
 REM Command file for Sphinx documentation
 
-set SPHINXBUILD=sphinx-build
+if "%%SPHINXBUILD%%" == "" (
+\tset SPHINXBUILD=sphinx-build
+)
 set BUILDDIR=%(rbuilddir)s
 set ALLSPHINXOPTS=-d %%BUILDDIR%%/doctrees %%SPHINXOPTS%% %(rsrcdir)s
 if NOT "%%PAPER%%" == "" (

tests/test_autodoc.py

@@ -169,8 +169,9 @@ def test_format_signature():
     assert formatsig('method', 'H.foo', H.foo1, 'a', None) == '(a)'
     assert formatsig('method', 'H.foo', H.foo2, None, None) == '(b, *c)'
 
-    # test exception handling
+    # test exception handling (exception is caught and args is '')
-    raises(TypeError, formatsig, 'function', 'int', int, None, None)
+    assert formatsig('function', 'int', int, None, None) == ''
+    del _warnings[:]
 
     # test processing by event handler
     assert formatsig('method', 'bar', H.foo1, None, None) == '42'