merge

CHANGES

@@ -3,6 +3,11 @@ Release 0.6.5 (in development)
 
 * #338: Fix running with ``-C`` under Windows.
 
+* 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
   ``literalinclude`` directive work correctly if not used together.
 

doc/config.rst

@@ -271,9 +271,8 @@ Project information
 
 .. confval:: pygments_style
 
-   The style name to use for Pygments highlighting of source code.  Default is
+   The style name to use for Pygments highlighting of source code.  The default
-   ``'sphinx'``, which is a builtin style designed to match Sphinx' default
+   style is selected by the theme for HTML output, and ``'sphinx'`` otherwise.
-   style.
 
    .. versionchanged:: 0.3
       If the value is a fully-qualified name of a custom Pygments style class,

doc/ext/autosummary.rst

@@ -85,18 +85,6 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts:
             sphinx.environment.BuildEnvironment
             sphinx.util.relative_uri
 
-   * You can specify a custom template with the ``template`` option.
-     For example, ::
-
-         .. autosummary::
-            :template: mytemplate.rst
-
-            sphinx.environment.BuildEnvironment
-
-     would use the template :file:`mytemplate.rst` in your
-     :confval:`templates_path` to generate the pages for all entries
-     listed. See `Customizing templates`_ below.
-
 
 :program:`sphinx-autogen` -- generate autodoc stub pages
 --------------------------------------------------------
@@ -134,89 +122,3 @@ also use this new config value:
 
    The new files will be placed in the directories specified in the
    ``:toctree:`` options of the directives.
-
-
-Customizing templates
----------------------
-
-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.)
-
-.. note::
-
-   If you find yourself spending much time tailoring the stub templates, this
-   may indicate that it's a better idea to write custom narrative documentation
-   instead.
-
-Autosummary uses the following template files:
-
-- :file:`autosummary/base.rst` -- fallback template
-- :file:`autosummary/module.rst` -- template for modules
-- :file:`autosummary/class.rst` -- template for classes
-- :file:`autosummary/function.rst` -- template for functions
-- :file:`autosummary/attribute.rst` -- template for class attributes
-- :file:`autosummary/method.rst` -- template for class methods
-
-The following variables available in the templates:
-
-.. data:: name
-
-   Name of the documented object, excluding the module and class parts.
-
-.. data:: objname
-
-   Name of the documented object, excluding the module parts.
-
-.. data:: fullname
-
-   Full name of the documented object, including module and class parts.
-
-.. data:: module
-
-   Name of the module the documented object belongs to.
-
-.. data:: class
-
-   Name of the class the documented object belongs to.  Only available for
-   methods and attributes.
-
-.. data:: underline
-
-   A string containing ``len(full_name) * '='``.
-
-.. data:: members
-
-   List containing names of all members of the module or class.  Only available
-   for modules and classes.
-
-.. data:: functions
-
-   List containing names of "public" functions in the module.  Here, "public"
-   here means that the name does not start with an underscore. Only available
-   for modules.
-
-.. data:: classes
-
-   List containing names of "public" classes in the module.  Only available for
-   modules.
-
-.. data:: exceptions
-
-   List containing names of "public" exceptions in the module.  Only available
-   for modules.
-
-.. data:: methods
-
-   List containing names of "public" methods in the class.  Only available for
-   classes.
-
-.. data:: attributes
-
-   List containing names of "public" attributes in the class.  Only available
-   for classes.
-
-.. note::
-
-   You can use the :dir:`autosummary` directive in the stub pages.
-   Stub pages are generated also based on these directives.

sphinx/ext/autodoc.py

@@ -365,9 +365,13 @@ class Documenter(object):
             args = "(%s)" % self.args
         else:
             # try to introspect the signature
-            args = self.format_args()
+            try:
-        if args is None:
+                args = self.format_args()
-            return ''
+            except Exception, err:
+                self.directive.warn('error while formatting arguments for '
+                                    '%s: %s' % (self.fullname, err))
+                args = None
+
         retann = self.retann
 
         result = self.env.app.emit_firstresult(
@@ -644,12 +648,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)
@@ -849,7 +848,6 @@ class ClassDocumenter(ModuleLevelDocumenter):
         return ret
 
     def format_args(self):
-        args = None
         # for classes, the relevant signature is the __init__ method's
         initmeth = self.get_attr(self.object, '__init__', None)
         # classes without __init__ method, default __init__ or

sphinx/writers/latex.py

@@ -734,6 +734,8 @@ class LaTeXTranslator(nodes.NodeVisitor):
 
     def visit_enumerated_list(self, node):
         self.body.append('\\begin{enumerate}\n' )
+        if 'start' in node:
+            self.body.append('\\setcounter{enumi}{%d}\n' % (node['start'] - 1))
     def depart_enumerated_list(self, node):
         self.body.append('\\end{enumerate}\n' )
 

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'