From c0f9828b3c23745de26ec9749af0fd856ea06a66 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Fri, 3 May 2024 12:55:08 +1200
Subject: [PATCH] Docs: Add autoref role

Use new `autoref` role when using single backticks. Allows automatic mapping to a cmd ref or a cell ref.
---
 docs/source/conf.py |  3 +++
 docs/util/cmdref.py | 11 ++++++++++-
 2 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/docs/source/conf.py b/docs/source/conf.py
index 8e30fcc7c..bfabe60e5 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -41,6 +41,9 @@ html_static_path = ['_static', "_images"]
 pygments_style = 'colorful'
 highlight_language = 'none'
 
+# default single quotes to attempt auto reference, or fallback to code
+default_role = 'autoref'
+
 extensions = ['sphinx.ext.autosectionlabel', 'sphinxcontrib.bibtex']
 
 if os.getenv("READTHEDOCS"):
diff --git a/docs/util/cmdref.py b/docs/util/cmdref.py
index ce010471c..aac899388 100644
--- a/docs/util/cmdref.py
+++ b/docs/util/cmdref.py
@@ -1,6 +1,8 @@
 # based on https://github.com/ofosos/sphinxrecipes/blob/master/sphinxrecipes/sphinxrecipes.py
 
 from docutils.parsers.rst import directives
+from docutils.parsers.rst.states import Inliner
+from sphinx.application import Sphinx
 from sphinx.domains import Domain, Index
 from sphinx.domains.std import StandardDomain
 from sphinx.roles import XRefRole
@@ -228,7 +230,12 @@ class CellDomain(CommandDomain):
         TagIndex
     }
 
-def setup(app):
+def autoref(name, rawtext, text, lineno, inliner: Inliner,
+            options=None, content=None):
+    role = 'cell:ref' if text[0] == '$' else 'cmd:ref'
+    return inliner.interpreted(rawtext, text, role, lineno)
+
+def setup(app: Sphinx):
     app.add_domain(CommandDomain)
     app.add_domain(CellDomain)
 
@@ -249,5 +256,7 @@ def setup(app):
         ('cell-cell', '')
     StandardDomain.initial_data['anonlabels']['tagindex'] =\
         ('cell-tag', '')
+
+    app.add_role('autoref', autoref)
     
     return {'version': '0.2'}