DOP-5604: dismissible-skills-card directive (#664)

* RstSpec and postprocess handler for dismissible skills card

* Use DismissibleSkillsCard node

* Clean postprocess

* Correct errors

* Fix types

* PR feedback

* remove unused import

* add postprocess test

Author: mmeigs

snooty/postprocess.py

@@ -1992,6 +1992,47 @@ def exit_node(self, fileid_stack: FileIdStack, node: n.Node) -> None:
             self.collapsible_detected = False
 
 
+class DismissibleSkillsCardHandler(Handler):
+    """Handles 'dismissible-skills-card' directives on a page.
+    Only one is allowed per page. Adds the data to page AST options."""
+
+    @dataclass
+    class DismissibleSkillsCard:
+        skill: str
+        url: str
+
+    def __init__(self, context: Context) -> None:
+        super().__init__(context)
+        self.dismissible_skills_card: Optional[
+            DismissibleSkillsCardHandler.DismissibleSkillsCard
+        ] = None
+
+    def enter_page(self, fileid_stack: FileIdStack, page: Page) -> None:
+        self.dismissible_skills_card = None
+
+    def enter_node(self, fileid_stack: FileIdStack, node: n.Node) -> None:
+        if not isinstance(node, n.Directive) or node.name != "dismissible-skills-card":
+            return
+        if self.dismissible_skills_card:
+            self.context.diagnostics[fileid_stack.current].append(
+                DuplicateDirective(node.name, node.span[0])
+            )
+
+        skill = node.options.get("skill")
+        url = node.options.get("url")
+        if skill and url:
+            self.dismissible_skills_card = self.DismissibleSkillsCard(
+                skill=skill, url=url
+            )
+
+    def exit_page(self, fileid_stack: FileIdStack, page: Page) -> None:
+        if self.dismissible_skills_card:
+            page.ast.options["dismissible_skills_card"] = {
+                "skill": self.dismissible_skills_card.skill,
+                "url": self.dismissible_skills_card.url,
+            }
+
+
 class NestedDirectiveHandler(Handler):
     """Prevents a directive from being nested deeper than intended on a page and from being used twice in a single page."""
 
@@ -2261,6 +2302,7 @@ class Postprocessor:
             ImageHandler,
             CollapsibleHandler,
             WayfindingHandler,
+            DismissibleSkillsCardHandler,
             MethodSelectorHandler,
             MultiPageTutorialHandler,
             ComposableTutorialHandler,

snooty/rstspec.toml

@@ -878,6 +878,16 @@ help = "Content chosen to be displayed"
 options.selections = {type = "string", required = true}
 content_type = "block"
 
+[directive."mongodb:dismissible-skills-card"]
+help = "A dismissible card that links to Skills"
+options.skill = {type = "string", required = true}
+options.url = {type = "string", required = true}
+example = """
+.. dismissible-skills-card::
+   :skill: CRUD Operations
+   :url: https://learn.mongodb.com/courses/crud-operations-in-mongodb
+"""
+
 ###### Misc.
 [directive.atf-image]
 help = "Path to the image to use for the above-the-fold header image"

snooty/test_postprocess.py

@@ -4770,3 +4770,27 @@ def test_composable_collisions() -> None:
         assert len(diagnostics) == 2
         assert isinstance(diagnostics[0], DuplicateDirective)
         assert isinstance(diagnostics[1], UnexpectedDirectiveOrder)
+
+
+def test_dismissible_skills_card() -> None:
+    with make_test(
+        {
+            Path(
+                "source/index.txt"
+            ): """
+===================
+Heading of the page
+===================
+
+.. dismissible-skills-card::
+   :skill: WOW Lightsaber Skill
+   :url: https://learn.mongodb.com/courses/crud-operations-in-mongodb
+
+""",
+        }
+    ) as result:
+        page = result.pages[FileId("index.txt")]
+        assert (page.ast.options.get("dismissible_skills_card")) == {
+            "skill": "WOW Lightsaber Skill",
+            "url": "https://learn.mongodb.com/courses/crud-operations-in-mongodb",
+        }