[Python-modules-commits] r17467 - in packages/sphinx/trunk/debian (3 files)
nikratio-guest at users.alioth.debian.org
nikratio-guest at users.alioth.debian.org
Wed Jun 15 17:07:22 UTC 2011
Date: Wednesday, June 15, 2011 @ 17:07:20
Author: nikratio-guest
Revision: 17467
Backported upstream patches for signature extraction from docstring. Patch is not enabled by default yet, because there are issues with disabling the feature by defaut. See https://bitbucket.org/birkenfeld/sphinx/issue/718
Added:
packages/sphinx/trunk/debian/patches/docstring_parse.diff
Modified:
packages/sphinx/trunk/debian/changelog
packages/sphinx/trunk/debian/patches/series
Modified: packages/sphinx/trunk/debian/changelog
===================================================================
--- packages/sphinx/trunk/debian/changelog 2011-06-15 08:44:06 UTC (rev 17466)
+++ packages/sphinx/trunk/debian/changelog 2011-06-15 17:07:20 UTC (rev 17467)
@@ -1,13 +1,19 @@
sphinx (1.0.7-5) UNRELEASED; urgency=low
+ [ Jakub Wilk ]
* Bump standards version to 3.9.2 (no changes needed).
* Bump minimum required version of jQuery to 1.4.
* Use python (>= 2.6.6-14~) as an alternative build-dependency to
python-simplejson. The latter package is only needed for python2.5, and
python-defaults 2.6.6-14 doesn't support it anymore.
- -- Jakub Wilk <jwilk at debian.org> Tue, 31 May 2011 02:45:50 +0200
+ [ Nikolaus Rath ]
+ * Backport upstream changesets a8b0ef275438 and de340a6098c7 to allow
+ extraction of function signature from docstring for extension modules.
+ Closes: 630409.
+ -- Nikolaus Rath <Nikolaus at rath.org> Wed, 15 Jun 2011 11:39:44 -0400
+
sphinx (1.0.7-4) unstable; urgency=low
* When Sphinx crashes, show 10 stack frames (instead of a single one).
Added: packages/sphinx/trunk/debian/patches/docstring_parse.diff
===================================================================
--- packages/sphinx/trunk/debian/patches/docstring_parse.diff (rev 0)
+++ packages/sphinx/trunk/debian/patches/docstring_parse.diff 2011-06-15 17:07:20 UTC (rev 17467)
@@ -0,0 +1,217 @@
+Description: Backport upstream commit de340a6098c7 and a8b0ef275438
+Bug-Debian: http://bugs.debian.org/630409
+Bug: https://bitbucket.org/birkenfeld/sphinx/issue/564
+Forwarded: not-needed
+diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst
+--- a/doc/ext/autodoc.rst
++++ b/doc/ext/autodoc.rst
+@@ -260,6 +260,22 @@
+
+ .. versionadded:: 1.0
+
++.. confval:: autodoc_docstring_signature
++
++ Functions imported from C modules cannot be introspected, and therefore the
++ signature for such functions cannot be automatically determined. However, it
++ is an often-used convention to put the signature into the first line of the
++ function's docstring.
++
++ If this boolean value is set to ``True``, autodoc will look at the
++ first line of the docstring for functions and methods, and if it
++ looks like a signature, use the line as the signature and remove it
++ from the docstring content.
++
++ The default is ``True``.
++
++ .. versionadded:: 1.1
++
+
+ Docstring preprocessing
+ -----------------------
+diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py
+--- a/sphinx/ext/autodoc.py
++++ b/sphinx/ext/autodoc.py
+@@ -426,13 +426,13 @@
+ # etc. don't support a prepended module name
+ self.add_line(u' :module: %s' % self.modname, '<autodoc>')
+
+- def get_doc(self, encoding=None):
++ def get_doc(self, encoding=None, ignore=1):
+ """Decode and return lines of the docstring(s) for the object."""
+ docstring = self.get_attr(self.object, '__doc__', None)
+ if docstring:
+ # make sure we have Unicode docstrings, then sanitize and split
+ # into lines
+- return [prepare_docstring(force_decode(docstring, encoding))]
++ return [prepare_docstring(force_decode(docstring, encoding), ignore)]
+ return []
+
+ def process_doc(self, docstrings):
+@@ -833,7 +833,53 @@
+ return modname, parents + [base]
+
+
+-class FunctionDocumenter(ModuleLevelDocumenter):
++class DocstringSignatureMixin(object):
++ """
++ Mixin for FunctionDocumenter and MethodDocumenter to provide the
++ feature of reading the signature from the docstring.
++ """
++
++ def _find_signature(self, encoding=None):
++ docstrings = Documenter.get_doc(self, encoding, 2)
++ if len(docstrings) != 1:
++ return
++ doclines = docstrings[0]
++ setattr(self, '__new_doclines', doclines)
++ if not doclines:
++ return
++ # match first line of docstring against signature RE
++ match = py_ext_sig_re.match(doclines[0])
++ if not match:
++ return
++ exmod, path, base, args, retann = match.groups()
++ # the base name must match ours
++ if not self.objpath or base != self.objpath[-1]:
++ return
++ # ok, now jump over remaining empty lines and set the remaining
++ # lines as the new doclines
++ i = 1
++ while i < len(doclines) and not doclines[i].strip():
++ i += 1
++ setattr(self, '__new_doclines', doclines[i:])
++ return args, retann
++
++ def get_doc(self, encoding=None, ignore=1):
++ lines = getattr(self, '__new_doclines', None)
++ if lines is not None:
++ return [lines]
++ return Documenter.get_doc(self, encoding, ignore)
++
++ def format_signature(self):
++ if self.args is None and self.env.config.autodoc_docstring_signature:
++ # only act if a signature is not explicitly given already, and if
++ # the feature is enabled
++ result = self._find_signature()
++ if result is not None:
++ self.args, self.retann = result
++ return Documenter.format_signature(self)
++
++
++class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):
+ """
+ Specialized Documenter subclass for functions.
+ """
+@@ -847,8 +893,8 @@
+ def format_args(self):
+ if inspect.isbuiltin(self.object) or \
+ inspect.ismethoddescriptor(self.object):
+- # can never get arguments of a C function or method
+- return None
++ # cannot introspect arguments of a C function or method
++ pass
+ try:
+ argspec = inspect.getargspec(self.object)
+ except TypeError:
+@@ -937,7 +983,7 @@
+ self.add_line(_(u' Bases: %s') % ', '.join(bases),
+ '<autodoc>')
+
+- def get_doc(self, encoding=None):
++ def get_doc(self, encoding=None, ignore=1):
+ content = self.env.config.autoclass_content
+
+ docstrings = []
+@@ -1010,7 +1056,7 @@
+ pass
+
+
+-class MethodDocumenter(ClassLevelDocumenter):
++class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter):
+ """
+ Specialized Documenter subclass for methods (normal, static and class).
+ """
+@@ -1225,6 +1271,7 @@
+ 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_config_value('autodoc_docstring_signature', True, True)
+ app.add_event('autodoc-process-docstring')
+ app.add_event('autodoc-process-signature')
+ app.add_event('autodoc-skip-member')
+diff --git a/sphinx/util/docstrings.py b/sphinx/util/docstrings.py
+--- a/sphinx/util/docstrings.py
++++ b/sphinx/util/docstrings.py
+@@ -12,7 +12,7 @@
+ import sys
+
+
+-def prepare_docstring(s):
++def prepare_docstring(s, ignore=1):
+ """
+ Convert a docstring into lines of parseable reST. Return it as a list of
+ lines usable for inserting into a docutils ViewList (used as argument
+@@ -20,18 +20,19 @@
+ this docstring and following content.
+ """
+ lines = s.expandtabs().splitlines()
+- # Find minimum indentation of any non-blank lines after first line.
++ # Find minimum indentation of any non-blank lines after ignored lines.
+ margin = sys.maxint
+- for line in lines[1:]:
++ for line in lines[ignore:]:
+ content = len(line.lstrip())
+ if content:
+ indent = len(line) - content
+ margin = min(margin, indent)
+- # Remove indentation.
+- if lines:
+- lines[0] = lines[0].lstrip()
++ # Remove indentation from ignored lines.
++ for i in range(ignore):
++ if i < len(lines):
++ lines[i] = lines[i].lstrip()
+ if margin < sys.maxint:
+- for i in range(1, len(lines)): lines[i] = lines[i][margin:]
++ for i in range(ignore, len(lines)): lines[i] = lines[i][margin:]
+ # Remove any leading blank lines.
+ while lines and not lines[0]:
+ lines.pop(0)
+diff --git a/tests/test_autodoc.py b/tests/test_autodoc.py
+--- a/tests/test_autodoc.py
++++ b/tests/test_autodoc.py
+@@ -40,6 +40,7 @@
+ members = [],
+ member_order = 'alphabetic',
+ exclude_members = set(),
++ docstring_signatures = True,
+ )
+
+ directive = Struct(
+@@ -501,6 +502,13 @@
+ 'attribute', 'mdocattr')
+ del directive.env.temp_data['autodoc:class']
+
++ # test autodoc_docstring_signature
++ assert_result_contains(
++ '.. py:method:: DocstringSig.meth(FOO, BAR=1) -> BAZ', 'method',
++ 'test_autodoc.DocstringSig.meth')
++ assert_result_contains(
++ ' rest of docstring', 'method', 'test_autodoc.DocstringSig.meth')
++
+
+ # --- generate fodder ------------
+
+@@ -595,3 +603,12 @@
+
+ # should be documented as an alias
+ factory = dict
++
++
++class DocstringSig(object):
++ def meth(self):
++ """meth(FOO, BAR=1) -> BAZ
++First line of docstring
++
++ rest of docstring
++ """
Modified: packages/sphinx/trunk/debian/patches/series
===================================================================
--- packages/sphinx/trunk/debian/patches/series 2011-06-15 08:44:06 UTC (rev 17466)
+++ packages/sphinx/trunk/debian/patches/series 2011-06-15 17:07:20 UTC (rev 17467)
@@ -3,3 +3,4 @@
unversioned_grammar_pickle.diff
show_more_stack_frames.diff
fix_jquery_1.5_incompatibility.diff
+#docstring_parse.diff
More information about the Python-modules-commits
mailing list