"""adds link url in the global scope

sample use:

:xref:`Tiramisu <tiramisu>`

You must declare in the `conf.py`

::

    #---- xref links ----
    #import the xref.py extension
            xref_links = {"link_name" : ("user text", "url")}
    #link_name = "Sphinx External Links"
    #user_text = "modified External Links Extension"
    #url = "http://www.sphinx-doc.org/en/stable/ext/extlinks.html"
    #enables syntax like:
            " :xref:`tiramisu` "
            links = {
                    'tiramisu': ('Tiramisu', 'https://tiramisu.readthedocs.io/en/latest/'),
                    'tiramisu library': ('Tiramisu library homepage', 'https://forge.cloud.silique.fr/stove/tiramisu'),
                    }
            xref_links.update(links)



"""
from docutils import nodes

from sphinx.util import caption_ref_re

def xref( typ, rawtext, text, lineno, inliner, options={}, content=[] ):

    title = target = text
    titleistarget = True
    # look if explicit title and target are given with `foo <bar>` syntax
    brace = text.find('<')
    if brace != -1:
        titleistarget = False
        m = caption_ref_re.match(text)
        if m:
            target = m.group(2)
            title = m.group(1)
        else:
            # fallback: everything after '<' is the target
            target = text[brace+1:]
            title = text[:brace]

    link = xref.links[target]

    if brace != -1:
        pnode = nodes.reference(target, title, refuri=link[1])
    else:
        pnode = nodes.reference(target, link[0], refuri=link[1])

    return [pnode], []

def get_refs(app):

    xref.links = app.config.xref_links

def setup(app):

    app.add_config_value('xref_links', {}, True)
    app.add_role('xref', xref)
    app.connect("builder-inited", get_refs)