Add support for linking to JSON Schema Glossary entries.

Author: Julian

docs/index.rst

@@ -9,8 +9,7 @@ The extension currently provides a single Sphinx `role`:
 
 .. rst:role:: kw
 
-    Link to the current JSON Schema specification's definition of the keyword
-    provided.
+    Link to the current JSON Schema specification's definition of the keyword provided.
 
 For instance, writing:
 
@@ -22,7 +21,21 @@ will produce:
 
     Reference resolution in JSON Schema is done using the :kw:`$ref` keyword.
 
+In addition, the extension automatically populates the Sphinx glossary with terms from the `JSON Schema Glossary <https://json-schema.org/learn/glossary.html>`_, such that:
+
+    .. code-block:: rst
+
+        If a :term:`schema` has a :term:`meta-schema`, what do :term:`meta-schemas <meta-schema>` have?
+
+will produce:
+
+    If a :term:`schema` has a :term:`meta-schema`, what do :term:`meta-schemas <meta-schema>` have?
+
+
+Contributing
+------------
+
 What's here, albeit crude, has been used in some form for a long while by `jsonschema` (the Python library), but the hope is it may be useful to alternate implementations or users in general.
 Help is very much welcome to improve it!
 
-In the future support may be added for linking to different drafts, or for linking to `Understanding JSON Schema <https://json-schema.org/understanding-json-schema/index.html>`_.
+In particular, help adding support for other (historic or future) drafts, rather than just the single draft currently supported, would be great.

sphinx_json_schema_spec/__init__.py

@@ -42,47 +42,53 @@ def setup(app):
     CACHE.mkdir(exist_ok=True)
 
     documents = {
-        url: fetch_or_load(vocabulary_path=CACHE / f"{name}.html", url=url)
+        url: fetch_or_load(cache_path=CACHE / f"{name}.html", url=url)
         for name, url in VOCABULARIES.items()
     }
     app.add_role("kw", docutils_does_not_allow_using_classes(documents))
 
+    glossary = fetch_or_load(
+        cache_path=CACHE / "glossary.html",
+        url="https://json-schema.org/learn/glossary.html",
+    )
+    app.connect("missing-reference", missing_reference(glossary))
+
     return dict(parallel_read_safe=True)
 
 
-def fetch_or_load(vocabulary_path, url):
+def fetch_or_load(cache_path, url):
     """
-    Fetch a new specification or use the cache if it's current.
+    Fetch a new page or specification, or use the cache if it's current.
 
     Arguments:
 
-        vocabulary_path:
+        cache_path:
 
-            the local path to a cached vocabulary document
+            the local path to a (possibly not yet existing) cache for the file
 
         url:
 
-            the URL of the vocabulary document
+            the URL of the document
     """
 
     version = metadata.version("sphinx-json-schema-spec")
     headers = {"User-Agent": f"sphinx-json-schema-spec v{version}"}
 
     with suppress(FileNotFoundError):
-        modified = datetime.utcfromtimestamp(vocabulary_path.stat().st_mtime)
+        modified = datetime.utcfromtimestamp(cache_path.stat().st_mtime)
         date = modified.strftime("%a, %d %b %Y %I:%M:%S UTC")
         headers["If-Modified-Since"] = date
 
     request = urllib.request.Request(url, headers=headers)
     response = urllib.request.urlopen(request, cafile=certifi.where())
 
     if response.code == 200:
-        with vocabulary_path.open("w+b") as spec:
-            spec.writelines(response)
-            spec.seek(0)
-            return html.parse(spec).getroot()
+        with cache_path.open("w+b") as out:
+            out.writelines(response)
+            out.seek(0)
+            return html.parse(out).getroot()
 
-    return html.parse(vocabulary_path.read_bytes()).getroot()
+    return html.parse(cache_path.read_bytes()).getroot()
 
 
 def docutils_does_not_allow_using_classes(vocabularies):
@@ -149,3 +155,30 @@ def keyword(name, raw_text, text, lineno, inliner):
         return [reference], []
 
     return keyword
+
+
+def missing_reference(glossary):
+
+    terms = {
+        link.lstrip("#")
+        for _, _, link, _ in glossary.iterlinks()
+        if link.startswith("#")
+    }
+
+    def _missing_reference(app, env, node, contnod):
+        """
+        Resolve a reference to a JSON Schema Glossary term.
+        """
+
+        if node["reftype"] != "term":
+            return
+
+        target = node["reftarget"]
+        if target not in terms:
+            return
+
+        uri = f"https://json-schema.org/learn/glossary.html#{target}"
+
+        text = contnod.astext() if node["refexplicit"] else target
+        return nodes.reference(text, text, internal=False, refuri=uri)
+    return _missing_reference