def indexmarkup_role(typ, rawtext, text, lineno, inliner,
                     options={}, content=[]):
    """Role for PEP/RFC references that generate an index entry."""
    env = inliner.document.settings.env
    if not typ:
        typ = env.config.default_role
    else:
        typ = typ.lower()
    has_explicit_title, title, target = split_explicit_title(text)  # type: bool, unicode, unicode  # NOQA
    title = utils.unescape(title)
    target = utils.unescape(target)
    targetid = 'index-%s' % env.new_serialno('index')
    indexnode = addnodes.index()
    targetnode = nodes.target('', '', ids=[targetid])
    inliner.document.note_explicit_target(targetnode)
    if typ == 'pep':
        indexnode['entries'] = [
            ('single', _('Python Enhancement Proposals; PEP %s') % target,
             targetid, '', None)]
        anchor = ''  # type: unicode
        anchorindex = target.find('#')
        if anchorindex > 0:
            target, anchor = target[:anchorindex], target[anchorindex:]
        if not has_explicit_title:
            title = "PEP " + utils.unescape(title)
        try:
            pepnum = int(target)
        except ValueError:
            msg = inliner.reporter.error('invalid PEP number %s' % target,
                                         line=lineno)
            prb = inliner.problematic(rawtext, rawtext, msg)
            return [prb], [msg]
        ref = inliner.document.settings.pep_base_url + 'pep-%04d' % pepnum
        sn = nodes.strong(title, title)
        rn = nodes.reference('', '', internal=False, refuri=ref+anchor,
                             classes=[typ])
        rn += sn
        return [indexnode, targetnode, rn], []
    elif typ == 'rfc':
        indexnode['entries'] = [
            ('single', 'RFC; RFC %s' % target, targetid, '', None)]
        anchor = ''
        anchorindex = target.find('#')
        if anchorindex > 0:
            target, anchor = target[:anchorindex], target[anchorindex:]
        if not has_explicit_title:
            title = "RFC " + utils.unescape(title)
        try:
            rfcnum = int(target)
        except ValueError:
            msg = inliner.reporter.error('invalid RFC number %s' % target,
                                         line=lineno)
            prb = inliner.problematic(rawtext, rawtext, msg)
            return [prb], [msg]
        ref = inliner.document.settings.rfc_base_url + inliner.rfc_url % rfcnum
        sn = nodes.strong(title, title)
        rn = nodes.reference('', '', internal=False, refuri=ref+anchor,
                             classes=[typ])
        rn += sn
        return [indexnode, targetnode, rn], []

def wikipedia_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
    has_title, title, target = split_explicit_title(text)
    title = utils.unescape(title)
    target = utils.unescape(target)
    target = target.replace(' ', '_')
    refnode = nodes.reference(title, title, refuri=WIKIPEDIA_URI % target)
    return [refnode], []

    def __call__(self, name, rawtext, text, lineno, inliner,
                 options={}, content=[]):

        text = docutils.utils.unescape(text)
        has_title, title, reftext = split_explicit_title(text)

        warnings = []
        try:
            where, what = self.find_ref(reftext)
            url = self.to_url(where, what)
            if not has_title:
                title = self.to_title(where, what)
        except JavarefError as e:
            url = None
            warnings.append(e.reason)

        if url:
            # if no scheme, assume a local path relative to the src root
            if not urlparse(url).scheme:
                docdir = os.path.dirname(inliner.document.current_source)
                if docdir != self.env.srcdir:
                    url = os.path.relpath(self.env.srcdir, docdir) + '/' + url

            ref = docutils.nodes.reference('', '', internal=False, refuri=url)
            ref.append(docutils.nodes.literal(rawsource=title, text=title))
        else:
            ref = docutils.nodes.literal(rawsource=title, text=title)

        return [ref], [inliner.reporter.warning(w, line=lineno) for w in warnings]

def blogref_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
    """
    Inserts a reference to the blog entry of the specified date.
    
    Instead of writing ``:doc:`/blog/2011/0406```
    it is better to write ``:blogref:`20110406```
    because the latter works between Sphinx trees and also supports archived blog entries.
    
    """
    # thanks to http://docutils.sourceforge.net/docs/howto/rst-roles.html
    # this code originally from roles.pep_reference_role
    #~ print 20130315, rawtext, text, utils.unescape(text)
    has_explicit_title, title, target = split_explicit_title(text)
    try:
        date = i2d(int(target))
    except ValueError:
        msg = inliner.reporter.error(
            'Invalid text %r: must be an integer date of style "20130315" .'
            % text, line=lineno)
        prb = inliner.problematic(rawtext, rawtext, msg)
        return [prb], [msg]
    #~ print repr(env)
    #~ raise Exception(20130315)
    #~ ref = inliner.document.settings.pep_base_url
           #~ + inliner.document.settings.pep_file_url_template % date)
    roles.set_classes(options)
    #~ from django.conf import settings
    #~ shown_text = settings.SITE.dtos(date)
    env = inliner.document.settings.env
    if not has_explicit_title:
        title = date.strftime(env.settings.get('today_fmt', '%Y-%m-%d'))
    title = utils.unescape(title)
    return [nodes.reference(rawtext, title,
                            refuri=get_blog_url(date),
                            **options)], []

def user_role(name, rawtext, text, lineno, inliner, options=None, content=None):
    """Sphinx role for linking to a user profile. Defaults to linking to
    Github profiles, but the profile URIS can be configured via the
    ``issues_user_uri`` config value.

    Examples: ::

        :user:`sloria`

    Anchor text also works: ::

        :user:`Steven Loria <sloria>`
    """
    options = options or {}
    content = content or []
    has_explicit_title, title, target = split_explicit_title(text)

    target = utils.unescape(target).strip()
    title = utils.unescape(title).strip()
    config = inliner.document.settings.env.app.config
    if config.issues_user_uri:
        ref = config.issues_user_uri.format(user=target)
    else:
        ref = "https://github.com/{0}".format(target)
    if has_explicit_title:
        text = title
    else:
        text = "@{0}".format(target)

    link = nodes.reference(text=text, refuri=ref, **options)
    return [link], []

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 blogref_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
    # thanks to http://docutils.sourceforge.net/docs/howto/rst-roles.html
    # this code originally from roles.pep_reference_role
    #~ print 20130315, rawtext, text, utils.unescape(text)
    has_explicit_title, title, target = split_explicit_title(text)
    try:
        date = i2d(int(target))
    except ValueError:
        msg = inliner.reporter.error(
            'Invalid text %r: must be an integer date of style "20130315" .'
            % text, line=lineno)
        prb = inliner.problematic(rawtext, rawtext, msg)
        return [prb], [msg]
    #~ print repr(env)
    #~ raise Exception(20130315)
    #~ ref = inliner.document.settings.pep_base_url
           #~ + inliner.document.settings.pep_file_url_template % date)
    roles.set_classes(options)
    #~ from django.conf import settings
    #~ shown_text = settings.SITE.dtos(date)
    env = inliner.document.settings.env
    if not has_explicit_title:
        title = date.strftime(env.settings.get('today_fmt', '%Y-%m-%d'))
    title = utils.unescape(title)
    return [nodes.reference(rawtext, title,
                            refuri=get_blog_url(env, date),
                            **options)], []

def php_class_role(typ, rawtext, text, lineno, inliner, options={},
                   content=[]):
    text = utils.unescape(text)
    env = inliner.document.settings.env
    base_url = env.app.config.api_url
    has_explicit_title, title, full_class = split_explicit_title(text)

    try:
        full_url = base_url % full_class.replace('\\', '/') + '.html'
    except (TypeError, ValueError):
        env.warn(
            env.docname, 'unable to expand %s api_url with base '
            'URL %r, please make sure the base contains \'%%s\' '
            'exactly once' % (typ, base_url))
        full_url = base_url + utils.escape(full_class)
    if not has_explicit_title:
        class_name = full_class.lstrip('\\')
        ns = class_name.rfind('\\')
        if ns != -1:
            class_name = class_name[ns + 1:]
        title = class_name
    list = [
        nodes.reference(
            title, title, internal=False, refuri=full_url, reftitle=full_class)
    ]
    pnode = nodes.literal('', '', *list)
    return [pnode], []

def php_phpfunction_role(typ,
                         rawtext,
                         text,
                         lineno,
                         inliner,
                         options={},
                         content=[]):
    text = utils.unescape(text)
    has_explicit_title, title, full_function = split_explicit_title(text)

    full_url = 'http://php.net/manual/en/function.%s.php' % lower(
        full_function.replace('_', '-'))

    if not has_explicit_title:
        title = full_function
    list = [
        nodes.reference(
            title,
            title,
            internal=False,
            refuri=full_url,
            reftitle=full_function)
    ]
    pnode = nodes.literal('', '', *list)
    return [pnode], []

	def find_doxygen_link(name, rawtext, text, lineno, inliner, options={}, content=[]):
		text = utils.unescape(text)
		# from :name:`title <part>`
		has_explicit_title, title, part = split_explicit_title(text)
		warning_messages = []
		if tag_file:
			url = find_url(tag_file, part)
			try:
				url = find_url2(app.env.doxylink_cache[cache_name]['mapping'], part)
			except LookupError as error:
				warning_messages.append('Error while parsing `%s`. Is not a well-formed C++ function call or symbol. If this is not the case, it is a doxylink bug so please report it. Error reported was: %s' % (part, error))
			if url:
				
				#If it's an absolute path then the link will work regardless of the document directory
				#Also check if it is a URL (i.e. it has a 'scheme' like 'http' or 'file')
				if os.path.isabs(rootdir) or urlparse.urlparse(rootdir).scheme:
					full_url = join(rootdir, url['file'])
				#But otherwise we need to add the relative path of the current document to the root source directory to the link
				else:
					relative_path_to_docsrc = os.path.relpath(app.env.srcdir, os.path.dirname(inliner.document.current_source))
					full_url = join(relative_path_to_docsrc, '/', rootdir, url['file']) #We always use the '/' here rather than os.sep since this is a web link avoids problems like documentation/.\../library/doc/ (mixed slashes)
				
				if url['kind'] == 'function' and app.config.add_function_parentheses and not normalise(title)[1]:
					title = join(title, '()')
				
				pnode = nodes.reference(title, title, internal=False, refuri=full_url)
				return [pnode], []
			#By here, no match was found
			warning_messages.append('Could not find match for `%s` in `%s` tag file' % (part, tag_filename))
		else:
			warning_messages.append('Could not find match for `%s` because tag file not found' % (part))
		
		pnode = nodes.inline(rawsource=title, text=title)
		return [pnode], [inliner.reporter.warning(message, line=lineno) for message in warning_messages]

def index_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
    # create new reference target
    env = inliner.document.settings.env
    targetid = 'index-%s' % env.new_serialno('index')
    targetnode = nodes.target('', '', ids=[targetid])
    # split text and target in role content
    has_explicit_title, title, target = split_explicit_title(text)
    title = utils.unescape(title)
    target = utils.unescape(target)
    # if an explicit target is given, we can process it as a full entry
    if has_explicit_title:
        entries = process_index_entry(target, targetid)
    # otherwise we just create a "single" entry
    else:
        # but allow giving main entry
        main = ''
        if target.startswith('!'):
            target = target[1:]
            title = title[1:]
            main = 'main'
        entries = [('single', target, targetid, main)]
    indexnode = addnodes.index()
    indexnode['entries'] = entries
    set_role_source_info(inliner, lineno, indexnode)
    textnode = nodes.Text(title, title)
    return [indexnode, targetnode, textnode], []

def arxiv_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
    text = utils.unescape(text)
    has_explicit_title, title, part = split_explicit_title(text)
    full_url = 'https://arxiv.org/abs/' + part
    if not has_explicit_title:
        title = 'arXiv:' + part
    pnode = nodes.reference(title, title, internal=False, refuri=full_url)
    return [pnode], []

 def role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
     text = utils.unescape(text)
     has_explicit_title, symbol, title = split_explicit_title(text)
     try:
         kind, filename, anchor = lookup_url(app, tagfile, symbol)
     except KeyError, e:
         inliner.reporter.warning(unicode(e.args[0]), line=lineno)
         return [nodes.Text(title)], []

def gh_issue(typ, rawtext, text, lineno, inliner, options={}, content=[]):
    text = utils.unescape(text)
    has_explicit_title, title, part = split_explicit_title(text)
    if not has_explicit_title:
        title = 'issue #%s' % part
    full_url = 'https://github.com/cms-dev/cms/issues/%s' % part

    retnode = nodes.reference(title, title, internal=False, refuri=full_url, **options)
    return [retnode], []

    def gh_blob(typ, rawtext, text, lineno, inliner, options={}, content=[]):
        text = utils.unescape(text)
        has_explicit_title, title, part = split_explicit_title(text)
        if not has_explicit_title:
            title = part
        full_url = 'https://github.com/cms-dev/cms/blob/v%s/%s' % (app.config.release, part)

        refnode = nodes.reference(title, title, internal=False, refuri=full_url, **options)
        return [refnode], []

def php_phpclass_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
    text = utils.unescape(text)
    has_explicit_title, title, full_class = split_explicit_title(text)

    full_url = 'http://php.net/manual/en/class.%s.php' % string.lower(full_class)

    if not has_explicit_title:
        title = full_class
    list = [nodes.reference(title, title, internal=False, refuri=full_url, reftitle=full_class)]
    pnode = nodes.literal('', '', *list)
    return [pnode], []

def icon_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
    has_explicit_title, label, target = split_explicit_title(text)
    css_class = target

    label = label if has_explicit_title else class_to_label(css_class)

    config = inliner.document.settings.env.config
    if config._raw_config['tags'].eval_condition('html'):
        return [IconNode(css_class=css_class, label=label)], []

    return [nodes.Text(label)], []

    def gh_tree(typ, rawtext, text, lineno, inliner, options={}, content=[]):
        text = utils.unescape(text)
        has_explicit_title, title, part = split_explicit_title(text)
        if not has_explicit_title:
            title = part
        full_url = 'https://github.com/cms-dev/cms/tree/v%s/%s' % (app.config.release, part)

        refnode = nodes.reference(title, title, internal=False, refuri=full_url, **options)
        retnode = nodes.literal(role=typ.lower(), classes=[typ])
        retnode += refnode
        return [retnode], []

def releaseref_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
    config = inliner.document.settings.env.config
    text = text.replace("|version|", config.version)
    text = text.replace("|release|", config.release)

    has_explicit_title, title, target = split_explicit_title(text)
    if not has_explicit_title:
        title = os.path.basename(target)

    node = nodes.reference(rawtext, title, refuri=target, **options)

    return [node], []

 def role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
     has_explicit, title, other = split_explicit_title(utils.unescape(text))
     args = [other]
     if use_explicit:
         args.append(has_explicit)
     result = func(*args)
     if isinstance(result, (list, tuple)):
         url, title = result
     else:
         url = result
     node = nodes.raw("", u"<a href='{url}'>{title}</a>".format(title=title, url=html_escape(url)), format="html")
     return [node], []