diff --git a/CHANGES b/CHANGES index acc3ce1ca..f824827f7 100644 --- a/CHANGES +++ b/CHANGES @@ -55,6 +55,7 @@ Features added * Automatically compile ``*.mo`` files from ``*.po`` files when :confval:`gettext_auto_build` is True (default) and ``*.po`` is newer than ``*.mo`` file. +* #623: :mod:`~sphinx.ext.viewcode` support imported function/class aliases. Bugs fixed ---------- diff --git a/doc/ext/viewcode.rst b/doc/ext/viewcode.rst index 6e77914d3..f2b6c9283 100644 --- a/doc/ext/viewcode.rst +++ b/doc/ext/viewcode.rst @@ -18,3 +18,23 @@ from the source to the description will also be inserted. There are currently no configuration values for this extension; you just need to add ``'sphinx.ext.viewcode'`` to your :confval:`extensions` value for it to work. + +There is also an additional config value: + +.. confval:: viewcode_import + + If this is ``True``, viewcode extension will follow alias objects that + imported from another module such as functions, classes and attributes. + As side effects, this option + else they produce nothing. The default is ``True``. + + .. warning:: + + :confval:`viewcode_import` **imports** the modules to be followed real + location. If any modules have side effects on import, these will be + executed by ``viewcode`` when ``sphinx-build`` is run. + + If you document scripts (as opposed to library modules), make sure their + main routine is protected by a ``if __name__ == '__main__'`` condition. + + .. versionadded:: 1.3 diff --git a/sphinx/ext/viewcode.py b/sphinx/ext/viewcode.py index 4a62bf6d6..9976ecc4a 100644 --- a/sphinx/ext/viewcode.py +++ b/sphinx/ext/viewcode.py @@ -9,21 +9,43 @@ :license: BSD, see LICENSE for details. """ +import traceback + from six import iteritems, text_type from docutils import nodes from sphinx import addnodes from sphinx.locale import _ from sphinx.pycode import ModuleAnalyzer +from sphinx.util import get_full_modname from sphinx.util.nodes import make_refnode +def _get_full_modname(app, modname, attribute): + try: + return get_full_modname(modname, attribute) + except AttributeError: + # sphinx.ext.viewcode can't follow class instance attribute + # then AttributeError logging output only verbose mode. + app.verbose('Didn\'t find %s in %s' % (attribute, modname)) + return None + except Exception as e: + # sphinx.ext.viewcode follow python domain directives. + # because of that, if there are no real modules exists that specified + # by py:function or other directives, viewcode emits a lot of warnings. + # It should be displayed only verbose mode. + app.verbose(traceback.format_exc().rstrip()) + app.verbose('viewcode can\'t import %s, failed with error "%s"' % + (modname, e)) + return None + + def doctree_read(app, doctree): env = app.builder.env if not hasattr(env, '_viewcode_modules'): env._viewcode_modules = {} - def has_tag(modname, fullname, docname): + def has_tag(modname, fullname, docname, refname): entry = env._viewcode_modules.get(modname, None) try: analyzer = ModuleAnalyzer.for_module(modname) @@ -36,11 +58,11 @@ def doctree_read(app, doctree): code = analyzer.code if entry is None or entry[0] != code: analyzer.find_tags() - entry = code, analyzer.tags, {} + entry = code, analyzer.tags, {}, refname env._viewcode_modules[modname] = entry elif entry is False: return - code, tags, used = entry + _, tags, used, _ = entry if fullname in tags: used[fullname] = docname return True @@ -53,10 +75,14 @@ def doctree_read(app, doctree): if not isinstance(signode, addnodes.desc_signature): continue modname = signode.get('module') + fullname = signode.get('fullname') + refname = modname + if env.config.viewcode_import: + modname = _get_full_modname(app, modname, fullname) if not modname: continue fullname = signode.get('fullname') - if not has_tag(modname, fullname, env.docname): + if not has_tag(modname, fullname, env.docname, refname): continue if fullname in names: # only one link per name, please @@ -95,7 +121,7 @@ def collect_pages(app): for modname, entry in iteritems(env._viewcode_modules): if not entry: continue - code, tags, used = entry + code, tags, used, refname = entry # construct a page name for the highlighted source pagename = '_modules/' + modname.replace('.', '/') # highlight the source using the builder's highlighter @@ -112,7 +138,7 @@ def collect_pages(app): maxindex = len(lines) - 1 for name, docname in iteritems(used): type, start, end = tags[name] - backlink = urito(pagename, docname) + '#' + modname + '.' + name + backlink = urito(pagename, docname) + '#' + refname + '.' + name lines[start] = ( '