add a custom role for references with literal link text

Closes #24.

Signed-off-by: Ruth Fuchss <[email protected]>

README.md

@@ -166,6 +166,8 @@ This extension adds custom roles that can be used in rST.
 Currently implemented:
 
 - `spellexception` - Includes the provided text in `<spellexception></spellexception>`, which makes it possible to exclude it from a spell checker.
+- `monoref` - Renders the provided reference in code-style, which excludes the link text from the spell checker.
+   You can provide either just the link (for example, ``:monoref:`www.example.com` ``, which results in `www.example.com` as the link text and `https://www.example.com` as the link URL) or a separate link text and URL (for example, ``:monoref:`xyzcommand <www.example.com>` ``).
 
 ### Config options
 

custom-rst-roles/__init__.py

@@ -10,7 +10,28 @@ def spellexception_role(
     return [node], []
 
 
+def literalref_role(
+    name, rawtext, text, lineno, inliner, options=None, content=None
+):
+
+    if "<" in text and ">" in text:
+        linktext = text.split("<")[0].strip()
+        linkurl = text.split("<")[1].split(">")[0].strip()
+    else:
+        linktext = text
+        linkurl = text
+
+    if not linkurl.startswith("http"):
+        linkurl = "https://" + linkurl
+
+    node = nodes.reference("", "", internal=False, refuri=linkurl)
+    node.append(nodes.literal(text=linktext))
+
+    return [node], []
+
+
 def setup(app):
     app.add_role("spellexception", spellexception_role)
+    app.add_role("literalref", literalref_role)
 
     return

setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = lxd-sphinx-extensions
-version = 0.0.14
+version = 0.0.15
 author = Ruth Fuchss
 author_email = [email protected]
 description = A collection of Sphinx extensions used in LXD