def autodoc_add_srcref(app, what, name, obj, options, lines):
"""Add a reference to the module's source code.
This is being added as listener to the
`autodoc-process-docstring <http://sphinx-doc.org/ext/autodoc.html#event-autodoc-process-docstring>`_ signal.
"""
if what == 'module':
s = srcref(obj)
if s:
# We must add it *after* the module description (not
# before) because also autosummary gets the docstring
# processed by this handler, and the overview table in
# the parent module would show always that same sentence.
# I tried whether autosummary is intelligent and removes
# admonitions when generating the summary: unfortunately
# not.
# 20151006 app.env.config.html_context.update(source_code_link=s)
if True:
lines += (SRCREF_TEMPLATE % s).splitlines()
else:
s = (SRCREF_TEMPLATE_BEFORE % s).splitlines()
# s = (SIDEBAR % s).splitlines()
s.reverse()
for ln in s:
lines.insert(0, ln)
def coderef_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
text = utils.unescape(text)
has_explicit_title, title, target = split_explicit_title(text)
try:
modname, name = target.rsplit('.', 1)
except ValueError:
raise Exception("Don't know how to import name %s" % target)
mod = import_module(modname)
try:
value = getattr(mod, name, None)
except AttributeError:
raise Exception("No name '%s' in module '%s'" % (name, modname))
#~ raise Exception("20130908 %s " % lines)
if isinstance(value, type):
if value.__module__ != modname:
raise Exception("20130908 %r != %r" % (value.__module__, modname))
url = srcref(mod)
lines, line_no = inspect.getsourcelines(value)
if line_no:
url += "#" + str(line_no)
if not has_explicit_title:
pass
pnode = nodes.reference(title, title, internal=False, refuri=url)
return [pnode], []
def html_page_context(app, pagename, templatename, context, doctree):
# experimental. no result yet.
# print(20151006, pagename, context.keys())
if pagename.startswith('api/') and pagename != "api/index":
modname = pagename[4:]
mod = import_module(modname)
s = srcref(mod)
if s:
tpl = """<p align="right"><a href="{0}">[source]</a></p>"""
context.update(source_code_link=tpl.format(s))
def unused_srcref_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
text = utils.unescape(text)
has_explicit_title, title, target = split_explicit_title(text)
url = srcref(target)
try:
full_url = base_url % part
except (TypeError, ValueError):
inliner.reporter.warning(
'unable to expand %s extlink with base URL %r, please make '
'sure the base contains \'%%s\' exactly once'
% (typ, base_url), line=lineno)
full_url = base_url + part
if not has_explicit_title:
if prefix is None:
title = full_url
else:
title = prefix + part
pnode = nodes.reference(title, title, internal=False, refuri=full_url)
return [pnode], []
def process_signature(app, what, name, obj, options, signature,
return_annotation):
# experimental. not yet used.
# trying to get source links à la django doc.
# test it in atelier with `$ inv clean -b bd`
# currently this gives
# Exception occurred:
# File ".../atelier/setup.py", line 3, in <module>
# exec(compile(fd.read(), fn, 'exec'))
# IOError: [Errno 2] No such file or directory: 'atelier/setup_info.py'
# if signature or return_annotation:
# raise Exception(
# "20170118 {!r} {!r} {!r} {!r} {!r} {!r}".format(
# what, name, obj, options, signature,
# return_annotation))
if what == 'module':
assert not signature
s = srcref(obj)
if s:
signature = " [{}]".format(s)
# signature = " [foo]"
print(20170118, signature)
return (signature, return_annotation)