✨ New: add .glossary for attrs_block (#719)

MyST follows Pandoc definition-lists, to denote lists of term -> definition. ```markdown Term 1 : Definition Term 2 : Definition ``` It should be easy for users to turn one of these lists into a glossary, where each term is uniquely referenceable across the entire project. This commit, allows this, via adding a `.glossary` class to the list: ```` {.glossary} Term 1 : Definition Term 2 : Definition ````
executablebooks · Feb 23, 2023 · 7692f87 · 7692f87
1 parent 7fe6411
commit 7692f87
Show file tree

Hide file tree

Showing 6 changed files with 71 additions and 2 deletions.
diff --git a/myst_parser/mdit_to_docutils/base.py b/myst_parser/mdit_to_docutils/base.py
@@ -1518,6 +1518,7 @@ def render_dl(self, token: SyntaxTreeNode) -> None:
         node = nodes.definition_list(classes=["simple", "myst"])
         self.copy_attributes(token, node, ("class", "id"))
         self.add_line_and_source_path(node, token)
+        make_terms = ("glossary" in node["classes"]) and (self.sphinx_env is not None)
         with self.current_node_context(node, append=True):
             item = None
             for child in token.children or []:
@@ -1529,8 +1530,21 @@ def render_dl(self, token: SyntaxTreeNode) -> None:
                             child.children[0].content if child.children else ""
                         )
                         self.add_line_and_source_path(term, child)
-                        with self.current_node_context(term, append=True):
+                        with self.current_node_context(term):
                             self.render_children(child)
+                        if make_terms:
+                            from sphinx.domains.std import make_glossary_term
+
+                            term = make_glossary_term(
+                                self.sphinx_env,  # type: ignore
+                                term.children,
+                                None,  # type: ignore
+                                term.source,
+                                term.line,
+                                node_id=None,  # type: ignore
+                                document=self.document,
+                            )
+                        self.current_node.append(term)
                 elif child.type == "dd":
                     if item is None:
                         error = self.reporter.error(

diff --git a/tests/test_renderers/fixtures/myst-config.txt b/tests/test_renderers/fixtures/myst-config.txt
@@ -341,7 +341,7 @@ a
 <string>:1: (WARNING/2) Invalid 'align' attribute value: 'other' [myst.attribute]
 .
 
-[attr_block] --myst-enable-extensions=attrs_block
+[attrs_block] --myst-enable-extensions=attrs_block
 .
 {#myid1 .class1 .class2}
 {#myid2 .class3}

diff --git a/tests/test_sphinx/sourcedirs/extended_syntaxes/conf.py b/tests/test_sphinx/sourcedirs/extended_syntaxes/conf.py
@@ -12,6 +12,8 @@
     "colon_fence",
     "linkify",
     "tasklist",
+    "attrs_inline",
+    "attrs_block",
 ]
 myst_number_code_blocks = ["typescript"]
 myst_html_meta = {

diff --git a/tests/test_sphinx/sourcedirs/extended_syntaxes/index.md b/tests/test_sphinx/sourcedirs/extended_syntaxes/index.md
@@ -39,6 +39,15 @@ Term 3
 
   : other
 
+{#myid1 .glossary}
+term
+:  definition
+
+other term
+:  other definition
+
+{term}`other term`
+
 :::{figure-md} target
 :class: other
 

diff --git a/tests/test_sphinx/test_sphinx_builds/test_extended_syntaxes.html b/tests/test_sphinx/test_sphinx_builds/test_extended_syntaxes.html
@@ -103,6 +103,31 @@ <h1>
       </p>
      </dd>
     </dl>
+    <dl class="simple myst glossary" id="myid1">
+     <dt id="term-term">
+      term
+     </dt>
+     <dd>
+      <p>
+       definition
+      </p>
+     </dd>
+     <dt id="term-other-term">
+      other term
+     </dt>
+     <dd>
+      <p>
+       other definition
+      </p>
+     </dd>
+    </dl>
+    <p>
+     <a class="reference internal" href="#term-other-term">
+      <span class="xref std std-term">
+       other term
+      </span>
+     </a>
+    </p>
     <figure class="other align-default" id="target">
      <img alt="fun-fish" src="_images/fun-fish.png"/>
      <figcaption>

diff --git a/tests/test_sphinx/test_sphinx_builds/test_extended_syntaxes.xml b/tests/test_sphinx/test_sphinx_builds/test_extended_syntaxes.xml
@@ -61,6 +61,25 @@
                 <definition>
                     <paragraph>
                         other
+        <definition_list classes="simple myst glossary" ids="myid1" names="myid1">
+            <definition_list_item>
+                <term ids="term-term">
+                    term
+                    <index entries="('single',\ 'term',\ 'term-term',\ 'main',\ None)">
+                <definition>
+                    <paragraph>
+                        definition
+            <definition_list_item>
+                <term ids="term-other-term">
+                    other term
+                    <index entries="('single',\ 'other\ term',\ 'term-other-term',\ 'main',\ None)">
+                <definition>
+                    <paragraph>
+                        other definition
+        <paragraph>
+            <pending_xref refdoc="index" refdomain="std" refexplicit="False" reftarget="other term" reftype="term" refwarn="True">
+                <inline classes="xref std std-term">
+                    other term
         <figure classes="other" ids="target" names="target">
             <image alt="fun-fish" candidates="{'*': 'fun-fish.png'}" uri="fun-fish.png">
             <caption>