DOP-1242: Warn about deprecated directives (#180)

Author: sophstad

snooty/rstparser.py

@@ -408,6 +408,14 @@ def run(self) -> List[docutils.nodes.Node]:
         node["options"] = self.options
         self.add_name(node)
 
+        # If directive is deprecated, warn
+        if self.directive_spec.deprecated == True:
+            node.append(
+                self.state.document.reporter.warning(
+                    f'Directive "{self.name}" has been deprecated', line=line
+                )
+            )
+
         # If this is an rstobject, we need to generate a target property
         if rstobject_spec is not None:
             prefix = rstobject_spec.prefix + "." if rstobject_spec.prefix else ""

snooty/rstspec.toml

@@ -13,7 +13,6 @@ charts_theme = ["light", "dark"]
 
 [directive.default-domain]
 argument_type = "string"
-deprecated = true
 
 [directive.div]
 deprecated = true

snooty/test_parser.py

@@ -1543,6 +1543,28 @@ def test_problematic() -> None:
     check_ast_testing_string(page.ast, "<root><paragraph></paragraph></root>")
 
 
+def test_deprecated() -> 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,
+        """
+.. raw:: html
+
+   <div>Test raw directive</div>
+""",
+    )
+    page.finish(diagnostics)
+    assert len(diagnostics) == 1
+    check_ast_testing_string(
+        page.ast,
+        """<root><directive name="raw"><directive_argument><text>html</text></directive_argument><FixedTextElement /></directive></root>""",
+    )
+
+
 def test_definition_list() -> None:
     path = ROOT_PATH.joinpath(Path("test.rst"))
     project_config = ProjectConfig(ROOT_PATH, "", source="./")

snooty/test_postprocess.py

@@ -68,9 +68,6 @@ def test_expand_includes(backend: Backend) -> None:
                 <heading id="skip-includes">
                     <text>Skip includes</text>
                 </heading>
-                <directive name="default-domain">
-                    <text>mongodb</text>
-                </directive>
                 <directive name="meta" keywords="connect">
                 </directive>
             </section>
@@ -156,7 +153,7 @@ def test_role_explicit_title(backend: Backend) -> None:
     assert isinstance(ast, n.Root)
 
     # Assert that ref_roles with an explicit title work
-    paragraph = cast(Any, ast).children[1].children[4].children[1].children[2]
+    paragraph = cast(Any, ast).children[1].children[3].children[1].children[2]
     assert isinstance(paragraph, n.Paragraph)
     ref_role = paragraph.children[1]
     print(ast_to_testing_string(ref_role))
@@ -243,7 +240,7 @@ def test_target_titles(backend: Backend) -> None:
     # Assert that titles are correctly located
     section = ast.children[1]
     assert isinstance(section, n.Parent)
-    section = section.children[4]
+    section = section.children[3]
     assert isinstance(section, n.Parent)
     target1 = section.children[-2]
     target2 = section.children[-1]
@@ -263,12 +260,12 @@ def test_program_option(backend: Backend) -> None:
     assert isinstance(ast, n.Root)
 
     section: Any = ast.children[0]
-    include = section.children[3]
-    program1 = section.children[2]
+    include = section.children[2]
+    program1 = section.children[1]
     option1_1 = include.children[0]
-    option1_2 = section.children[4]
-    program2 = section.children[5]
-    option2_1 = section.children[6]
+    option1_2 = section.children[3]
+    program2 = section.children[4]
+    option2_1 = section.children[5]
 
     # Test directives
     check_ast_testing_string(
@@ -332,7 +329,7 @@ def test_program_option(backend: Backend) -> None:
     assert len(diagnostics) == 1, diagnostics
     assert isinstance(diagnostics[0], AmbiguousTarget)
 
-    roles = section.children[7].children
+    roles = section.children[6].children
     check_ast_testing_string(
         roles[0].children[0].children[0],
         """

test_data/test_postprocessor/source/a-program.txt

@@ -2,8 +2,6 @@
 A Program
 =========
 
-.. default-domain:: mongodb
-
 .. program:: a-program
 
 .. include:: /includes/option-version.rst

test_data/test_postprocessor/source/includes/test.rst

@@ -5,7 +5,5 @@
 Skip includes
 =============
 
-.. default-domain:: mongodb
-
 .. meta::
    :keywords: connect

test_data/test_postprocessor/source/index.txt

@@ -4,8 +4,6 @@
 Connection Limits and Cluster Tier
 ====================================
 
-.. default-domain:: mongodb
-
 .. meta::
    :keywords: connect
 

test_data/test_postprocessor/source/page1.txt

@@ -4,8 +4,6 @@
 Print this heading
 ==================
 
-.. default-domain:: mongodb
-
 .. meta::
    :keywords: connect
 

test_data/test_postprocessor/source/page2.txt

@@ -19,8 +19,6 @@
 Heading is not at the top for some reason
 =========================================
 
-.. default-domain:: mongodb
-
 .. meta::
    :keywords: connect