def doctree_read(app, doctree):
    # Add viewcode nodes for code elements referenced in the document.

    env = app.builder.env
    if not hasattr(env, '_viewcode_modules'):
        env._viewcode_modules = {}

    # handle desc (description) nodes (module contents)
    for objnode in doctree.traverse(addnodes.desc):
        if objnode.get('domain') != 'py':
            continue
        names = set()
        for signode in objnode:
            if not isinstance(signode, addnodes.desc_signature):
                continue
            modname = signode.get('module')
            if not modname:
                continue
            fullname = signode.get('fullname')
            if not _update_tags(env, modname, fullname):
                continue
            if fullname in names:
                # only one link per name, please
                continue
            names.add(fullname)
            pagename = '_modules/' + modname.replace('.', '/')
            # build up an xref and add it to the desc node
            onlynode = addnodes.only(expr='html')
            onlynode += addnodes.pending_xref(
                '', reftype='viewcode', refdomain='std', refexplicit=False,
                reftarget=pagename, refid=fullname,
                refdoc=env.docname)
            onlynode[0] += nodes.inline('', _('[source]'),
                                        classes=['viewcode-link'])
            signode += onlynode

    # handle index nodes (modules themselves)
    for objnode in doctree.traverse(addnodes.index):
        # extract module name by de-munging the "target" field
        index_target = objnode['entries'][0][2]
        if not index_target.startswith('module-'):
            continue
        modname = index_target.replace('module-', '', 1)
        _update_tags(env, modname)
        pagename = '_modules/' + modname.replace('.', '/')
        # build up an xref and add it in a new paragraph after the index node
        xref = addnodes.pending_xref(
            '', reftype='viewcode', refdomain='std', refexplicit=False,
            reftarget=pagename, refid='', refdoc=env.docname)
        xref += nodes.inline('', _('[source]'),
                                    classes=['viewcode-link'])
        idx = objnode.parent.index(objnode) + 1
        objnode.parent.insert(idx, nodes.paragraph('', '', xref))

    def handle_signature(self, sig, signode):
        name = self.options["name"]
        parameters = json.loads(self.options["parameters"]) if "parameters" in self.options else []
        return_v = json.loads(self.options["return"]) if "return" in self.options else ("", "")
        prefix = self.options["prefix"] if "prefix" in self.options else ""

        if not ("parameters" in self.options) or not ("return" in self.options):
            print("WARNING: No parameters or return set for '" + name + "'")

        signode += nodes.Text(prefix + " ", prefix + u"\xa0")
        xref = addnodes.pending_xref(
            ":ref:`" + return_v[1] + "`",
            refdomain="std",
            reftype="ref",
            reftarget=ws_re.sub(" ", return_v[1].lower()),
            refexplicit=False,
        )
        xref += nodes.Text(return_v[0], return_v[0])
        signode += xref
        signode += nodes.Text(" ", u"\xa0")

        signode += addnodes.desc_name(name, name)
        paramlist = addnodes.desc_parameterlist()
        for tn in parameters:
            param = addnodes.desc_parameter("", "", noemph=True)
            prefix = ""
            if len(tn) > 3 and tn[3] == "True":
                prefix += "ref "
            if len(tn) > 4 and tn[4] == "True":
                prefix += "out "

            if prefix != "":
                param += nodes.Text(prefix + " ", prefix + u"\xa0")

            xref = addnodes.pending_xref(
                ":ref:`" + tn[2] + "`",
                refdomain="std",
                reftype="ref",
                reftarget=ws_re.sub(" ", tn[2].lower()),
                refexplicit=False,
            )
            xref += nodes.Text(tn[0], tn[0])
            param += xref
            param += nodes.emphasis(" " + tn[1], u"\xa0" + tn[1])
            paramlist += param
        signode += paramlist

        return name, ""

    def add_shape_and_attrs(self, signode, modname, ftype, shape, attrs):
        # add shape 
        if shape:
            add_shape(signode, shape, modname=modname)
            #signode += nodes.Text(' '+shape)
        # add type ('float', 'interger', etc)
        if ftype or attrs:
            signode += nodes.emphasis(' [', ' [')
        if ftype:
            refnode = addnodes.pending_xref(
                '', refdomain='f', reftype='type', reftarget=ftype,
                modname=modname,)
            refnode += nodes.emphasis(ftype, ftype)
            signode += refnode
            #tnode = addnodes.desc_type(ftype, ftype)
            #tnode +=
            #signode += addnodes.desc_type(ftype, ftype)
            #signode += 
    #        signode += addnodes.desc_type('', '')
    #        self._parse_type(signode[-1], ftype)
        if attrs:
            if ftype: signode += nodes.emphasis(',',',')
            for iatt,att in enumerate(re.split('\s*,\s*', attrs)):
                if iatt:
                    signode += nodes.emphasis(',',',')
                if att.startswith('parameter'):
                    value = att.split('=')[1]
                    signode += nodes.emphasis('parameter=', 'parameter=')
                    convert_arithm(signode, value, modname=modname)
                else:
                    signode += nodes.emphasis(att,att)
            #signode += nodes.emphasis(attrs, attrs)

        if ftype or attrs:
            signode += nodes.emphasis(']', ']')

def mkYrefNode(target,text,rawtext,role,explicitText,lineno,options={}):
	"""Create hyperlink to yade target. Targets starting with literal 'yade.' are absolute, but the leading 'yade.' will be stripped from the link text. Absolute tergets are supposed to live in page named yade.[module].html, anchored at #yade.[module2].[rest of target], where [module2] is identical to [module], unless mapped over by moduleMap.
	
	Other targets are supposed to live in yade.wrapper (such as c++ classes)."""

	writer=__builtin__.writer # to make sure not shadowed by a local var
	import string
	if target.startswith('yade.'):
		module='.'.join(target.split('.')[0:2])
		module2=(module if module not in moduleMap.keys() else moduleMap[module])
		if target==module: target='' # to reference the module itself
		uri=('%%%s#%s'%(module2,target) if writer=='latex' else '%s.html#%s'%(module2,target))
		if not explicitText and module!=module2:
			text=module2+'.'+'.'.join(target.split('.')[2:])
		text=string.replace(text,'yade.','',1)
	elif target.startswith('external:'):
		exttarget=target.split(':',1)[1]
		if not explicitText: text=exttarget
		target=exttarget if '.' in exttarget else 'module-'+exttarget
		uri=(('%%external#%s'%target) if writer=='latex' else 'external.html#%s'%target)
	else:
		uri=(('%%yade.wrapper#yade.wrapper.%s'%target) if writer=='latex' else 'yade.wrapper.html#yade.wrapper.%s'%target)
		#print writer,uri
	if 0:
		refnode=addnodes.pending_xref(rawtext,reftype=role,refexplicit=explicitText,reftarget=target)
		#refnode.line=lineno
		#refnode+=nodes.literal(rawtext,text,classes=['ref',role])
		return [refnode],[]
		#ret.rawtext,reftype=role,
	else:
		return nodes.reference(rawtext,docutils.utils.unescape(text),refuri=uri,**options)

 def make_xref(self, rolename, domain, target, innernode=nodes.emphasis):
     if not rolename:
         return innernode(target, target)
     refnode = addnodes.pending_xref('', refdomain=domain, refexplicit=False,
                                     reftype=rolename, reftarget=target)
     refnode += innernode(target, target)
     return refnode

    def make_content(self, all_members):
        doc = self.item
        content = addnodes.desc_content()

        if doc.exports or doc.dependencies:
            with addto(content, nodes.field_list()) as fields:
                if doc.exports:
                    with addto(fields, nodes.field()) as field:
                        field += nodes.field_name('Exports', 'Exports')
                        with addto(field, nodes.field_body()) as body:
                            ref = doc['exports'] # warning: not the same as doc.exports
                            label = ref or '<anonymous>'
                            link = addnodes.pending_xref(
                                ref, nodes.paragraph(ref, label),
                                refdomain='js',
                                reftype='any',
                                reftarget=ref,
                            )
                            link['js:module'] = doc.name
                            body += link

                if doc.dependencies:
                    with addto(fields, nodes.field()) as field:
                        self.make_dependencies(field, doc)

        if doc.doc:
            # FIXME: source offset
            self.directive.state.nested_parse(to_list(doc.doc, source=doc['sourcefile']), 0, content)

        self.directive.state.nested_parse(self.directive.content, 0, content)

        content += self.document_properties(all_members)

        return content

 def apply(self):
     config = self.document.settings.env.config
     github_project = config.github_project
     issue_pattern = config.github_issue_pattern
     if isinstance(issue_pattern, str_t):
         issue_pattern = re.compile(issue_pattern)
     for node in self.document.traverse(nodes.Text):
         parent = node.parent
         if isinstance(parent, (nodes.literal, nodes.FixedTextElement)):
             continue
         text = text_t(node)
         new_nodes = []
         last_issue_ref_end = 0
         for match in issue_pattern.finditer(text):
             head = text[last_issue_ref_end:match.start()]
             if head:
                 new_nodes.append(nodes.Text(head))
             last_issue_ref_end = match.end()
             issuetext = match.group(0)
             issue_id = match.group(1)
             refnode = pending_xref()
             refnode['reftarget'] = issue_id
             refnode['reftype'] = 'issue'
             refnode['refdomain'] = 'github'
             refnode['github_project'] = github_project
             reftitle = issuetext
             refnode.append(nodes.inline(
                 issuetext, reftitle, classes=['xref', 'issue']))
             new_nodes.append(refnode)
         if not new_nodes:
             continue
         tail = text[last_issue_ref_end:]
         if tail:
             new_nodes.append(nodes.Text(tail))
         parent.replace(node, new_nodes)

    def visit_link(self, mdnode):
        ref_node = nodes.reference()
        ref_node['refuri'] = mdnode.destination
        # TODO okay, so this is acutally not always the right line number, but
        # these mdnodes won't have sourcepos on them for whatever reason. This
        # is better than 0 though.
        ref_node.line = (mdnode.sourcepos[0][0] if mdnode.sourcepos
                         else mdnode.parent.sourcepos[0][0])
        if mdnode.title:
            ref_node['title'] = mdnode.title
        next_node = ref_node

        url_check = urlparse(mdnode.destination)
        if not url_check.scheme and not url_check.fragment:
            wrap_node = addnodes.pending_xref(
                reftarget=mdnode.destination,
                reftype='any',
                refexplicit=True,
                refwarn=True
            )
            # TODO also not correct sourcepos
            wrap_node.line = (mdnode.sourcepos[0][0] if mdnode.sourcepos
                              else mdnode.parent.sourcepos[0][0])
            if mdnode.title:
                wrap_node['title'] = mdnode.title
            wrap_node.append(ref_node)
            next_node = wrap_node

        self.current_node.append(next_node)
        self.current_node = ref_node

 def attach_type(self, node, type):
     # XXX: link to c?
     text = str(type)
     pnode = addnodes.pending_xref("", refdomain="cpp", reftype="type", reftarget=text, modname=None, classname=None)
     pnode["cpp:parent"] = self.env.temp_data.get("cpp:parent")
     pnode += nodes.Text(text)
     node += pnode

 def resolve_xref(self, env, fromdocname, builder,
                  typ, target, node, contnode):
     if typ == 'ref':
         if node['refexplicit']:
             # reference to anonymous label; the reference uses
             # the supplied link caption
             docname, labelid = self.data['anonlabels'].get(target, ('',''))
             sectname = node.astext()
         else:
             # reference to named label; the final node will
             # contain the section name after the label
             docname, labelid, sectname = self.data['labels'].get(target,
                                                                  ('','',''))
         if not docname:
             return None
         newnode = nodes.reference('', '', internal=True)
         innernode = nodes.emphasis(sectname, sectname)
         if docname == fromdocname:
             newnode['refid'] = labelid
         else:
             # set more info in contnode; in case the
             # get_relative_uri call raises NoUri,
             # the builder will then have to resolve these
             contnode = addnodes.pending_xref('')
             contnode['refdocname'] = docname
             contnode['refsectname'] = sectname
             newnode['refuri'] = builder.get_relative_uri(
                 fromdocname, docname)
             if labelid:
                 newnode['refuri'] += '#' + labelid
         newnode.append(innernode)
         return newnode
     elif typ == 'keyword':
         # keywords are oddballs: they are referenced by named labels
         docname, labelid, _ = self.data['labels'].get(target, ('','',''))
         if not docname:
             return None
         return make_refnode(builder, fromdocname, docname,
                             labelid, contnode)
     elif typ == 'option':
         progname = node['refprogram']
         docname, labelid = self.data['progoptions'].get((progname, target),
                                                         ('', ''))
         if not docname:
             return None
         return make_refnode(builder, fromdocname, docname,
                             labelid, contnode)
     else:
         objtypes = self.objtypes_for_role(typ) or []
         for objtype in objtypes:
             if (objtype, target) in self.data['objects']:
                 docname, labelid = self.data['objects'][objtype, target]
                 break
         else:
             docname, labelid = '', ''
         if not docname:
             return None
         return make_refnode(builder, fromdocname, docname,
                             labelid, contnode)

 def format_type(t):
     ref = addnodes.pending_xref(
         t, addnodes.literal_emphasis(t, t),
         refdomain='js', reftype='class', reftarget=t,
     )
     if mod:
         ref['js:module'] = mod
     return ref

 def handle_signature(self, sig, signode):
   name = self.options['name']
   parameters = json.loads(self.options['parameters']) if 'parameters' in self.options else []
   return_v = json.loads(self.options['return']) if 'return' in self.options else ("","")
   prefix = self.options['prefix'] if 'prefix' in self.options else ""
 
   if not ('parameters' in self.options) or not ('return' in self.options):
     print("WARNING: No parameters or return set for '" + name + "'")
   
   signode += nodes.Text(prefix + ' ', prefix + u'\xa0')
   xref = addnodes.pending_xref(
     ':ref:`' + return_v[1] + '`',
     refdomain='std',
     reftype='ref',
     reftarget=ws_re.sub(' ', return_v[1].lower()),
     refexplicit=False)
   xref += nodes.Text(return_v[0], return_v[0])
   signode += xref
   signode += nodes.Text(' ', u'\xa0')
     
   signode += addnodes.desc_name(name, name)
   paramlist = addnodes.desc_parameterlist()
   for tn in parameters:
     param = addnodes.desc_parameter('', '', noemph=True)
     prefix = ''
     if len(tn) > 3 and tn[3] == "True":
       prefix += "ref "
     if len(tn) > 4 and tn[4] == "True":
       prefix += "out "
     
     if prefix != "":
       param += nodes.Text(prefix + ' ', prefix + u'\xa0')
       
     xref = addnodes.pending_xref(
       ':ref:`' + tn[2] + '`',
       refdomain='std',
       reftype='ref',
       reftarget=ws_re.sub(' ', tn[2].lower()),
       refexplicit=False)
     xref += nodes.Text(tn[0], tn[0])
     param += xref
     param += nodes.emphasis(' '+tn[1], u'\xa0'+tn[1])
     paramlist += param
   signode += paramlist
   
   return name, ""

 def make_xref(self, rolename, domain, target,
               innernode=addnodes.literal_emphasis, contnode=None):
     if not rolename:
         return contnode or innernode(target, target)
     refnode = addnodes.pending_xref('', refdomain=domain, refexplicit=False,
                                     reftype=rolename, reftarget=target)
     refnode += contnode or innernode(target, target)
     return refnode

def get_xref(typ, target, title=None):
    if title is None:
        title = target
    ref = addnodes.pending_xref(title,
                                reftype=typ,
                                refdomain="xml",
                                reftarget=target)
    ref.append(nodes.literal(title, title))
    return ref

def doctree_read(app, doctree):
    env = app.builder.env
    if not hasattr(env, "_viewcode_modules"):
        env._viewcode_modules = {}

    def has_tag(modname, fullname, docname):
        entry = env._viewcode_modules.get(modname, None)
        try:
            analyzer = ModuleAnalyzer.for_module(modname)
        except Exception:
            env._viewcode_modules[modname] = False
            return
        if not isinstance(analyzer.code, str):
            code = analyzer.code.decode(analyzer.encoding)
        else:
            code = analyzer.code
        if entry is None or entry[0] != code:
            analyzer.find_tags()
            entry = code, analyzer.tags, {}
            env._viewcode_modules[modname] = entry
        elif entry is False:
            return
        code, tags, used = entry
        if fullname in tags:
            used[fullname] = docname
            return True

    for objnode in doctree.traverse(addnodes.desc):
        if objnode.get("domain") != "py":
            continue
        names = set()
        for signode in objnode:
            if not isinstance(signode, addnodes.desc_signature):
                continue
            modname = signode.get("module")
            if not modname:
                continue
            fullname = signode.get("fullname")
            if not has_tag(modname, fullname, env.docname):
                continue
            if fullname in names:
                # only one link per name, please
                continue
            names.add(fullname)
            pagename = "_modules/" + modname.replace(".", "/")
            onlynode = addnodes.only(expr="html")
            onlynode += addnodes.pending_xref(
                "",
                reftype="viewcode",
                refdomain="std",
                refexplicit=False,
                reftarget=pagename,
                refid=fullname,
                refdoc=env.docname,
            )
            onlynode[0] += nodes.inline("", _("[source]"), classes=["viewcode-link"])
            signode += onlynode

 def fake_node(domain, type, target, content, **attrs):
     contnode = nodes.emphasis(content, content)
     node = addnodes.pending_xref("")
     node["reftarget"] = target
     node["reftype"] = type
     node["refdomain"] = domain
     node.attributes.update(attrs)
     node += contnode
     return node, contnode

 def attach_type(self, node, type):
     # XXX: link to c?
     text = unicode(type)
     pnode = addnodes.pending_xref(
         '', refdomain='matlab', reftype='type',
         reftarget=text, modname=None, classname=None)
     pnode['matlab:parent'] = self.env.temp_data.get('matlab:parent')
     pnode += nodes.Text(text)
     node += pnode

def doctree_read(app, doctree):
    env = app.builder.env
    if not hasattr(env, '_viewcode_modules'):
        env._viewcode_modules = {}

    def has_tag(modname, fullname, docname, refname):
        entry = env._viewcode_modules.get(modname, None)
        try:
            analyzer = ModuleAnalyzer.for_module(modname)
        except Exception:
            env._viewcode_modules[modname] = False
            return
        if not isinstance(analyzer.code, text_type):
            code = analyzer.code.decode(analyzer.encoding)
        else:
            code = analyzer.code
        if entry is None or entry[0] != code:
            analyzer.find_tags()
            entry = code, analyzer.tags, {}, refname
            env._viewcode_modules[modname] = entry
        elif entry is False:
            return
        _, tags, used, _ = entry
        if fullname in tags:
            used[fullname] = docname
            return True

    for objnode in doctree.traverse(addnodes.desc):
        if objnode.get('domain') != 'py':
            continue
        names = set()
        for signode in objnode:
            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, refname):
                continue
            if fullname in names:
                # only one link per name, please
                continue
            names.add(fullname)
            pagename = '_modules/' + modname.replace('.', '/')
            onlynode = addnodes.only(expr='html')
            onlynode += addnodes.pending_xref(
                '', reftype='viewcode', refdomain='std', refexplicit=False,
                reftarget=pagename, refid=fullname,
                refdoc=env.docname)
            onlynode[0] += nodes.inline('', _('[source]'),
                                        classes=['viewcode-link'])
            signode += onlynode

 def apply(self):
     for citnode in self.document.traverse(nodes.citation_reference):
         cittext = citnode.astext()
         refnode = addnodes.pending_xref(cittext, reftype='citation',
                                         reftarget=cittext, refwarn=True,
                                         ids=citnode["ids"])
         refnode.line = citnode.line or citnode.parent.line
         refnode += nodes.Text('[' + cittext + ']')
         citnode.parent.replace(citnode, refnode)

 def make_checker_chaining(self):
     symbol = self.lookup_auto_symbol()
     if not symbol:
         return
     next_checkers = symbol.properties.get('flycheck-next-checkers')
     if not next_checkers:
         return
     title = nodes.title('', 'Chained syntax checkers')
     intro = nodes.paragraph()
     intro += nodes.Text('The following syntax checkers are ')
     chained = addnodes.pending_xref(
         'chained', reftype='term', refdomain='std', reftarget='chaining',
         refwarn=True, refexplicit=True, reftitle='chaining',
         refdoc=self.env.docname)
     chained += nodes.emphasis('', 'chained')
     intro += chained
     intro += nodes.Text(' after this syntax checker:')
     checker_list = nodes.enumerated_list()
     para = nodes.paragraph()
     para += checker_list
     outro = nodes.paragraph()
     outro += nodes.Text('The ')
     outro += nodes.strong('', 'first')
     outro += nodes.Text(' suitable syntax checker is used.')
     chaining = nodes.admonition(
         '', title, intro, para, outro,
         classes=['note', 'el-flycheck-checker-chaining'])
     for next_checker in next_checkers:
         xref = addnodes.pending_xref(
             next_checker.checker,
             reftype='flyc-checker', refdomain='el',
             refexplicit=False, reftarget=next_checker.checker,
             refwarn=False, refdoc=self.env.docname)
         set_role_source_info(self.state.inliner, self.lineno, xref)
         xref += nodes.literal('', next_checker.checker,
                               classes=['xref', 'el', 'el-flyc-checker'])
         para = nodes.paragraph()
         para += xref
         if next_checker.warnings_only:
             para += nodes.Text(', if there are only warnings')
         if next_checker.no_errors:
             para += nodes.Text(', if there are no errors')
         checker_list += nodes.list_item('', para)
     return chaining