[Python-checkins] r64297 - in doctools/trunk: CHANGES sphinx/ext/autodoc.py

Sun Jun 15 19:09:23 CEST 2008

Author: georg.brandl
Date: Sun Jun 15 19:09:23 2008
New Revision: 64297
Log:
Correctly report source location for docstrings included
with autodoc.
Modified:
 doctools/trunk/CHANGES
 doctools/trunk/sphinx/ext/autodoc.py
Modified: doctools/trunk/CHANGES
==============================================================================

--- doctools/trunk/CHANGES	(original)
+++ doctools/trunk/CHANGES	Sun Jun 15 19:09:23 2008
@@ -42,7 +42,8 @@
 which makes the builder select the one that matches best.
 
 * The new config value `exclude_trees` can be used to exclude whole
- subtrees from the search for source files.
+ subtrees from the search for source files. Thanks to Sebastian
+ Wiesner.
 
 * Defaults for configuration values can now be callables, which allows
 dynamic defaults.
@@ -58,6 +59,9 @@
 Bugs fixed
 ----------
 
+* Correctly report the source location for docstrings included with
+ autodoc.
+
 * Fix the LaTeX output of description units with multiple signatures.
 
 * Handle the figure directive in LaTeX output.
Modified: doctools/trunk/sphinx/ext/autodoc.py
==============================================================================
--- doctools/trunk/sphinx/ext/autodoc.py	(original)
+++ doctools/trunk/sphinx/ext/autodoc.py	Sun Jun 15 19:09:23 2008
@@ -33,6 +33,47 @@
 _module_charsets = {}
 
 
+class AutodocReporter(object):
+ """
+ A reporter replacement that assigns the correct source name
+ and line number to a system message, as recorded in a ViewList.
+ """
+ def __init__(self, viewlist, reporter):
+ self.viewlist = viewlist
+ self.reporter = reporter
+
+ def __getattr__(self, name):
+ return getattr(self.reporter, name)
+
+ def system_message(self, level, message, *children, **kwargs):
+ if 'line' in kwargs:
+ try:
+ source, line = self.viewlist.items[kwargs['line']]
+ except IndexError:
+ pass
+ else:
+ kwargs['source'] = source
+ kwargs['line'] = line
+ return self.reporter.system_message(level, message,
+ *children, **kwargs)
+
+ def debug(self, *args, **kwargs):
+ if self.reporter.debug_flag:
+ return self.system_message(0, *args, **kwargs)
+
+ def info(self, *args, **kwargs):
+ return self.system_message(1, *args, **kwargs)
+
+ def warning(self, *args, **kwargs):
+ return self.system_message(2, *args, **kwargs)
+
+ def error(self, *args, **kwargs):
+ return self.system_message(3, *args, **kwargs)
+
+ def severe(self, *args, **kwargs):
+ return self.system_message(4, *args, **kwargs)
+
+
 def isdescriptor(x):
 """Check if the object is some kind of descriptor."""
 for item in '__get__', '__set__', '__delete__':
@@ -65,8 +106,11 @@
 """Return the charset of the given module (cached in _module_charsets)."""
 if module in _module_charsets:
 return _module_charsets[module]
- filename = __import__(module, None, None, ['']).__file__
- if filename[-4:] in ('.pyc', '.pyo'):
+ try:
+ filename = __import__(module, None, None, ['']).__file__
+ except (ImportError, AttributeError):
+ return None
+ if filename[-4:].lower() in ('.pyc', '.pyo'):
 filename = filename[:-1]
 for line in [linecache.getline(filename, x) for x in (1, 2)]:
 match = _charset_re.search(line)
@@ -137,6 +181,8 @@
 lineno, indent='', filename_set=None, check_module=False):
 env = document.settings.env
 
+ result = None
+
 # first, parse the definition -- auto directives for classes and functions
 # can contain a signature which is then used instead of an autogenerated one
 try:
@@ -144,7 +190,7 @@
 except:
 warning = document.reporter.warning(
 'invalid signature for auto%s (%r)' % (what, name), line=lineno)
- return [warning], ViewList()
+ return [warning], result
 # fullname is the fully qualified name, base the name after the last dot
 fullname = (path or '') + base
 # path is the name up to the last dot
@@ -203,20 +249,17 @@
 # the name to put into the generated directive -- doesn't contain the module
 name_in_directive = '.'.join(objpath) or mod
 
- # make sure that the view list starts with an empty line. This is
- # necessary for some situations where another directive preprocesses
- # reST and no starting newline is present
- result = ViewList()
- result.append('', '')
-
 # now, import the module and get docstring(s) of object to document
 try:
 todoc = module = __import__(mod, None, None, ['foo'])
- if filename_set is not None and hasattr(module, '__file__') and module.__file__:
+ if hasattr(module, '__file__') and module.__file__:
 modfile = module.__file__
- if modfile.lower().endswith('.pyc') or modfile.lower().endswith('.pyo'):
+ if modfile[-4:].lower() in ('.pyc', '.pyo'):
 modfile = modfile[:-1]
- filename_set.add(modfile)
+ if filename_set is not None:
+ filename_set.add(modfile)
+ else:
+ modfile = None # e.g. for builtin and C modules
 for part in objpath:
 todoc = getattr(todoc, part)
 except (ImportError, AttributeError):
@@ -244,6 +287,12 @@
 (fullname, err), line=lineno))
 args = ''
 
+ # make sure that the view list starts with an empty line. This is
+ # necessary for some situations where another directive preprocesses
+ # reST and no starting newline is present
+ result = ViewList()
+ result.append('', '')
+
 # now, create the directive header
 result.append(indent + '.. %s:: %s%s' % (what, name_in_directive, args),
 '<autodoc>')
@@ -257,9 +306,14 @@
 if what != 'module':
 indent += ' '
 
+ if modfile:
+ sourcename = '%s:docstring of %s' % (modfile, fullname)
+ else:
+ sourcename = 'docstring of %s' % fullname
+
 # add content from docstrings
 for i, line in enumerate(get_doc(what, todoc, env)):
- result.append(indent + line, '<docstring of %s>' % fullname, i)
+ result.append(indent + line, sourcename, i)
 
 # add source content, if present
 if add_content:
@@ -349,12 +403,17 @@
 filename_set = set()
 warnings, result = generate_rst(what, name, members, inherited, undoc, content,
 state.document, lineno, filename_set=filename_set)
+ if result is None:
+ return warnings
 
 # record all filenames as dependencies -- this will at least partially make
 # automatic invalidation possible
 for fn in filename_set:
 state.document.settings.env.note_dependency(fn)
 
+ # use a custom reporter that correctly assigns lines to source and lineno
+ old_reporter = state.memo.reporter
+ state.memo.reporter = AutodocReporter(result, state.memo.reporter)
 if dirname == 'automodule':
 node = nodes.section()
 # hack around title style bookkeeping
@@ -362,12 +421,13 @@
 surrounding_section_level = state.memo.section_level
 state.memo.title_styles = []
 state.memo.section_level = 0
- state.nested_parse(result, content_offset, node, match_titles=1)
+ state.nested_parse(result, 0, node, match_titles=1)
 state.memo.title_styles = surrounding_title_styles
 state.memo.section_level = surrounding_section_level
 else:
 node = nodes.paragraph()
- state.nested_parse(result, content_offset, node)
+ state.nested_parse(result, 0, node)
+ state.memo.reporter = old_reporter
 return warnings + node.children
 
 def auto_directive(*args, **kwds):
