DOP 888: Add glossary support (#152)

Author: madelinezec

snooty/diagnostics.py

@@ -204,6 +204,21 @@ def __init__(
         self.name = name
 
 
+class MalformedGlossary(Diagnostic):
+    severity = Diagnostic.Level.error
+
+    def __init__(
+        self,
+        start: Union[int, Tuple[int, int]],
+        end: Union[None, int, Tuple[int, int]] = None,
+    ) -> None:
+        super().__init__(
+            f"Malformed glossary: glossary must contain only a definition list",
+            start,
+            end,
+        )
+
+
 class FailedToInheritRef(Diagnostic):
     severity = Diagnostic.Level.error
 

snooty/n.py

@@ -302,6 +302,12 @@ class TargetIdentifier(InlineParent):
     ids: List[str]
 
 
+@dataclass
+class InlineTarget(InlineParent, Target):
+    __slots__ = ()
+    type = "inline_target"
+
+
 @dataclass
 class Reference(InlineParent):
     __slots__ = ("refuri", "refname")

snooty/parser.py

@@ -13,6 +13,7 @@
 from functools import partial
 from pathlib import Path, PurePath
 from typing import Any, Dict, MutableSequence, Tuple, Optional, Set, List, Iterable
+from docutils.nodes import make_id
 from typing_extensions import Protocol
 import docutils.utils
 import watchdog.events
@@ -48,6 +49,7 @@
     InvalidURL,
     InvalidLiteralInclude,
     InvalidTableStructure,
+    MalformedGlossary,
 )
 
 # XXX: Work around to get snooty working with Python 3.8 until we can fix
@@ -60,7 +62,7 @@
 
 @dataclass
 class _DefinitionListTerm(n.InlineParent):
-    """A private node used for internal book-keeping that should not be exported to the AST."""
+    """A vate node used for internal book-keeping that should not be exported to the AST."""
 
     __slots__ = ()
     type = "definition_list_term"
@@ -427,6 +429,37 @@ def dispatch_departure(self, node: docutils.nodes.Node) -> None:
                     repr(popped),
                 )
 
+        if (
+            isinstance(popped, n.Directive)
+            and f"{popped.domain}:{popped.name}" == ":glossary"
+        ):
+
+            definition_list = next(popped.get_child_of_type(n.DefinitionList), None)
+
+            if definition_list is None:
+                return
+
+            if len(popped.children) != 1:
+                self.diagnostics.append(MalformedGlossary(util.get_line(node)))
+                return
+
+            if popped.options.get("sorted", False):
+                definition_list.children = sorted(
+                    definition_list.children,
+                    key=lambda DefinitionListItem: "".join(
+                        term.get_text() for term in DefinitionListItem.term
+                    ),
+                )
+
+            for item in definition_list.get_child_of_type(n.DefinitionListItem):
+                term_text = "".join(term.get_text() for term in item.term)
+                term_identifier = make_id(term_text)
+                identifier = n.TargetIdentifier(item.start, [], [term_identifier])
+                identifier.children = item.term[:]
+                target = n.InlineTarget(item.start, [], "std", "term", None)
+                target.children = [identifier]
+                item.term.append(target)
+
     def handle_directive(
         self, node: docutils.nodes.Node, line: int
     ) -> Optional[n.Node]:

snooty/test_parser.py

@@ -8,42 +8,16 @@
     DocUtilsParseError,
     CannotOpenFile,
     InvalidLiteralInclude,
+    MalformedGlossary,
 )
-from .parser import parse_rst, JSONVisitor, InlineJSONVisitor
+from .parser import parse_rst, JSONVisitor
 
 ROOT_PATH = Path("test_data")
 
 # Some of the tests in this file may seem a little weird around refs: the raw parser output
 # does NOT include postprocessing artifacts such as nonlocal link titles and intersphinx lookups.
 
 
-def test_inline_parser_references() -> None:
-    tabs_path = ROOT_PATH.joinpath(Path("test.rst"))
-    project_config = ProjectConfig(ROOT_PATH, "")
-    parser = rstparser.Parser(project_config, InlineJSONVisitor)
-
-    # Test a simple code-block
-    page, diagnostics = parse_rst(
-        parser,
-        tabs_path,
-        """
-`package management system <https://en.wikipedia.org/wiki/Package_manager>`_
-""",
-    )
-    page.finish(diagnostics)
-    assert diagnostics == []
-    print(ast_to_testing_string(page.ast))
-    check_ast_testing_string(
-        page.ast,
-        """
-        <root>
-        <reference refuri="https://en.wikipedia.org/wiki/Package_manager">
-        <text>package management system</text>
-        </reference>
-        </root>""",
-    )
-
-
 def test_tabs() -> None:
     tabs_path = ROOT_PATH.joinpath(Path("test_tabs.rst"))
     project_config = ProjectConfig(ROOT_PATH, "")
@@ -639,6 +613,123 @@ def test_accidental_indentation() -> None:
     assert len(diagnostics) == 1
 
 
+def test_glossary_node() -> None:
+    path = ROOT_PATH.joinpath(Path("test.rst"))
+    project_config = ProjectConfig(ROOT_PATH, "", source="./")
+    parser = rstparser.Parser(project_config, JSONVisitor)
+
+    page, diagnostics = parse_rst(
+        parser,
+        path,
+        """
+.. glossary::
+  :sorted:
+
+  _id
+    foofoobarbar
+
+  index 
+    foofoofoofoobarbarbarbar
+
+  $cmd
+    foobar
+    
+  aggregate
+    foofoofoobarbarbar
+  
+  
+""",
+    )
+    page.finish(diagnostics)
+
+    check_ast_testing_string(
+        page.ast,
+        """
+<root> 
+  <directive name="glossary" sorted="True">
+    <definitionList>       
+      <definitionListItem>         
+        <term>           
+          <text>$cmd</text>
+          <inline_target domain="std" name="term">            
+            <target_identifier ids="['cmd']">
+              <text>$cmd</text></target_identifier>           
+          </inline_target>         
+        </term>
+        <paragraph><text>foobar</text></paragraph>       
+      </definitionListItem>        
+
+      <definitionListItem>
+        <term>           
+          <text>_id</text>           
+          <inline_target domain="std" name="term">
+            <target_identifier ids="['id']">               
+              <text>_id</text>
+            </target_identifier>
+          </inline_target>         
+        </term>         
+        <paragraph><text>foofoobarbar</text></paragraph>
+      </definitionListItem>     
+
+      <definitionListItem>         
+        <term>           
+          <text>aggregate</text>
+          <inline_target domain="std" name="term">            
+            <target_identifier ids="['aggregate']">
+              <text>aggregate</text></target_identifier>           
+          </inline_target>         
+        </term>
+        <paragraph><text>foofoofoobarbarbar</text></paragraph>       
+      </definitionListItem>
+      
+      <definitionListItem>         
+        <term>           
+          <text>index</text>
+          <inline_target domain="std" name="term">            
+            <target_identifier ids="['index']">
+              <text>index</text></target_identifier>           
+          </inline_target>         
+        </term>
+        <paragraph><text>foofoofoofoobarbarbarbar</text></paragraph>       
+      </definitionListItem>
+    </definitionList>
+  </directive>
+</root>
+""",
+    )
+
+    page, diagnostics = parse_rst(
+        parser,
+        path,
+        """
+.. glossary::
+  :sorted:
+  
+""",
+    )
+
+    page.finish(diagnostics)
+
+    assert len(diagnostics) == 0
+
+    page, diagnostics = parse_rst(
+        parser,
+        path,
+        """
+.. glossary::
+
+  _id
+    foo
+  
+  This is a paragraph, not a definition list item.
+  
+""",
+    )
+    page.finish(diagnostics)
+    assert len(diagnostics) == 1
+    assert isinstance(diagnostics[0], MalformedGlossary)
+
+
 def test_cond() -> None:
     path = ROOT_PATH.joinpath(Path("test.rst"))
     project_config = ProjectConfig(ROOT_PATH, "", source="./")
@@ -1110,7 +1201,7 @@ def test_callable_target() -> None:
     )
 
 
-def test_no_hyperlink_references() -> None:
+def test_no_weird_targets() -> None:
     path = ROOT_PATH.joinpath(Path("test.rst"))
     project_config = ProjectConfig(ROOT_PATH, "", source="./")
     parser = rstparser.Parser(project_config, JSONVisitor)
@@ -1132,16 +1223,6 @@ def test_no_hyperlink_references() -> None:
         diagnostics[1], InvalidURL
     )
 
-    check_ast_testing_string(
-        page.ast,
-        """
-    <root>
-    <paragraph><reference refname="ios-universal-links"><text>universal link</text></reference></paragraph>
-    <paragraph><reference refname="ios-universal-links"><text>universal link</text></reference></paragraph>
-    </root>
-    """,
-    )
-
 
 def test_dates() -> None:
     path = ROOT_PATH.joinpath(Path("test.rst"))

snooty/util_test.py

@@ -107,4 +107,4 @@ def check_ast_testing_string(ast: Any, testing_string: str) -> None:
     """Ensure that an AST node matches the given testing XML string, using ast_to_testing_string()."""
     correct_tree = ET.fromstring(testing_string)
     evaluating_tree = ET.fromstring(ast_to_testing_string(ast))
-    assert_etree_equals(correct_tree, evaluating_tree)
+    assert_etree_equals(evaluating_tree, correct_tree)