refactor(glossary): switch to generated-only glossary source and reproducibility checks

.github/workflows/ci.yml

@@ -26,6 +26,12 @@ jobs:
       - name: Build documentation and check links
         run: ./make.py --check-links
 
+      - name: Verify glossary generation is reflected immediately
+        run: rm -f build/generated.glossary.rst && ./make.py --clear && test -f build/generated.glossary.rst
+
+      - name: Verify glossary HTML reproducibility
+        run: ./tools/verify-html-diff.py --mode repro --ref HEAD
+
       - name: Verify licensing metadata
         run: uvx reuse lint
 

README.rst

@@ -81,6 +81,27 @@ whenever you change a file by passing the ``--serve`` flag::
 
    ./make.py --serve
 
+For a full list of build flags, run::
+
+   ./make.py --help
+
+Glossary generation
+===================
+
+Glossary entries can be authored once and used to render both their chapter
+definitions and the glossary. The generated glossary output lives at
+``build/generated.glossary.rst``.
+
+``./make.py`` always regenerates ``build/generated.glossary.rst`` before a
+build, including ``--serve`` mode.
+
+Generate the glossary directly::
+
+   ./generate-glossary.py
+
+For reproducibility and cross-ref comparisons, see ``tools/README.rst``
+(``tools/verify-html-diff.py``).
+
 Checking links consistency
 ==========================
 

exts/ferrocene_spec/README.rst

@@ -139,6 +139,45 @@ Words and characters wrapped within ``$$`` are considered "literals": they will
 be rendered differently than syntactic categories, and they won't be considered
 by the extension when looking for syntactic categories.
 
+Glossary entries
+================
+
+The extension provides directives to keep glossary and chapter definitions in a
+single place, and to render a glossary from those entries.
+
+Use ``glossary-entry`` to declare a term. It accepts a term argument and one or
+both content blocks (``:glossary:`` and ``:chapter:``). ``:glossary-dp:`` is
+required for any entry exported to the glossary.
+
+Options:
+
+* ``:kind:`` selects the entry kind (``term``, ``code``, or ``syntax``).
+* ``:propagate:`` controls whether the chapter text is reused as glossary text
+  when ``:glossary:`` is omitted (``true`` or ``false``).
+* ``:glossary-dp:`` provides the glossary anchor ID (``fls_`` + alphanumeric).
+
+.. code-block:: rst
+
+   .. glossary-entry:: subject expression
+      :glossary-dp: fls_wee9stfk0abp
+      :kind: term
+      :propagate: false
+
+      :glossary:
+        :dp:`fls_xisqke87ert`
+        A :dt:`subject expression` is an :t:`expression` that controls
+        :t:`[for loop]s`, :t:`[if expression]s`, and :t:`[match expression]s`.
+
+      :chapter:
+        :dp:`fls_pwut2jbmk66k`
+        A :ds:`SubjectExpression` is any expression in category :s:`Expression`, except
+        :s:`StructExpression`.
+
+Use ``glossary-include`` to insert glossary content (typically the generated
+glossary file under ``build/generated.glossary.rst``) into a page, with
+optional ``:tag:`` and ``:start-after:`` filters, similar to the standard
+``include`` directive.
+
 Paragraph IDs
 =============
 

exts/ferrocene_spec/__init__.py

@@ -1,7 +1,14 @@
 # SPDX-License-Identifier: MIT OR Apache-2.0
 # SPDX-FileCopyrightText: The Ferrocene Developers
 
-from . import definitions, informational, syntax_directive, std_role, paragraph_ids
+from . import (
+    definitions,
+    glossary,
+    informational,
+    syntax_directive,
+    std_role,
+    paragraph_ids,
+)
 from . import items_with_rubric, sphinx_fixes
 from sphinx.domains import Domain
 
@@ -18,6 +25,8 @@ class SpecDomain(Domain):
         "informational-page": informational.build_directive("page"),
         "informational-section": informational.build_directive("section"),
         "items-with-rubric": items_with_rubric.ItemsWithRubricDirective,
+        "glossary-entry": glossary.GlossaryEntryDirective,
+        "glossary-include": glossary.GlossaryIncludeDirective,
     }
     object_types = definitions.get_object_types()
     indices = {}
@@ -38,6 +47,7 @@ def is_empty(data):
 def setup(app):
     app.add_domain(SpecDomain)
     definitions.setup(app)
+    glossary.setup(app)
     paragraph_ids.setup(app)
     informational.setup(app)
     items_with_rubric.setup(app)
@@ -61,5 +71,6 @@ def setup(app):
         # Version history:
         # - 0: initial implementation
         # - 1: changed how informational sections and pages are stored
-        "env_version": "1",
+        # - 2: added glossary-dp metadata to glossary entries
+        "env_version": "2",
     }