From 0df55077911c4c60a2894177533069898f6ee19e Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Mon, 13 Jan 2025 15:20:37 +1300
Subject: [PATCH] Docs: Improve autoref

Fix `help $cell` type references, as well as actually implement the fallback to yoscrypt.
---
 docs/source/conf.py |  6 +++++-
 docs/util/cmdref.py | 16 ++++++++++++----
 2 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/docs/source/conf.py b/docs/source/conf.py
index e544d938f..8ba74065e 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -18,8 +18,12 @@ html_static_path = ['_static', "_images"]
 # default to no highlight
 highlight_language = 'none'
 
-# default single quotes to attempt auto reference, or fallback to code
+# default single quotes to attempt auto reference, or fallback to yoscrypt
 default_role = 'autoref'
+rst_prolog = """
+.. role:: yoscrypt(code)
+   :language: yoscrypt
+"""
 
 extensions = ['sphinx.ext.autosectionlabel', 'sphinxcontrib.bibtex']
 
diff --git a/docs/util/cmdref.py b/docs/util/cmdref.py
index 203d9369e..da27860b3 100644
--- a/docs/util/cmdref.py
+++ b/docs/util/cmdref.py
@@ -715,10 +715,18 @@ class CellDomain(CommandDomain):
 
 def autoref(name, rawtext: str, text: str, lineno, inliner: Inliner,
             options=None, content=None):
-    role = 'cell:ref' if text[0] == '$' else 'cmd:ref'
-    if text.startswith("help ") and text.count(' ') == 1:
-        _, cmd = text.split(' ', 1)
-        text = f'{text} <{cmd}>'
+    words = text.split(' ')
+    if len(words) == 2 and words[0] == "help":
+        IsLinkable = True
+        thing = words[1]
+    else:
+        IsLinkable = len(words) == 1 and words[0][0] != '-'
+        thing = words[0]
+    if IsLinkable:
+        role = 'cell:ref' if thing[0] == '$' else 'cmd:ref'
+        text = f'{text} <{thing}>'
+    else:
+        role = 'yoscrypt'
     return inliner.interpreted(rawtext, text, role, lineno)
 
 def setup(app: Sphinx):