67 lines
1.7 KiB
Python
67 lines
1.7 KiB
Python
"""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)
|
|
|