DOP-1573: Add directive for banner support (#308)

* DOP-1573: Add directive for banner support

* Add support for banners in project.config

* DOP-1573: Explicitly copy node children as list

* Add test suite and variant enum

* Address feedback in domain and matching logic

* Add linter updates

* Multi-target and multi-banner support

* Update test_postprocess.py

* Ensure path comparisons for target occur relative to source

* Add basic multi-banner test case

* Added help string for banner directive

* Address last round of feedback

Author: casthewiz

snooty/parser.py

@@ -67,6 +67,7 @@
 from .types import (
     BuildIdentifierSet,
     FileId,
+    ParsedBannerConfig,
     ProjectConfig,
     SerializableType,
     StaticAsset,
@@ -1159,6 +1160,26 @@ def __init__(
 
         self.config.substitution_nodes = substitution_nodes
 
+        # Parse banner value and instantiate a banner node for postprocessing, if a banner value is defined.
+        for banner in self.config.banners:
+            if banner.value:
+
+                options = {"variant": banner.variant}
+                banner_node = ParsedBannerConfig(
+                    banner.targets,
+                    n.Directive((-1,), [], "mongodb", "banner", [], options),
+                )
+
+                page, banner_diagnostics = parse_rst(inline_parser, root, banner.value)
+                banner_node.node.children = page.ast.children
+                if banner_node.node.children:
+                    self.config.banner_nodes.append(banner_node)
+                if banner_diagnostics:
+                    backend.on_diagnostics(
+                        self.config.get_fileid(self.config.config_path),
+                        banner_diagnostics,
+                    )
+
         username = getpass.getuser()
         try:
             branch = subprocess.check_output(

snooty/postprocess.py

@@ -6,6 +6,7 @@
 import urllib.parse
 from collections import defaultdict
 from copy import deepcopy
+from pathlib import Path
 from typing import (
     Any,
     Callable,
@@ -41,7 +42,7 @@
 from .eventparser import EventParser, FileIdStack
 from .page import Page
 from .target_database import TargetDatabase
-from .types import FileId, ProjectConfig, SerializableType
+from .types import FileId, ParsedBannerConfig, ProjectConfig, SerializableType
 from .util import SOURCE_FILE_EXTENSIONS
 
 logger = logging.getLogger(__name__)
@@ -546,6 +547,79 @@ def __call__(self, fileid_stack: FileIdStack, node: n.Node) -> None:
             )
 
 
+class BannerHandler:
+    """Traverse a series of pages matching specified targets in Snooty.toml
+    and append Banner directive nodes"""
+
+    def __init__(self, banners: List[ParsedBannerConfig], root: Path) -> None:
+        self.banners = banners
+        self.root = root
+
+    def __find_target_insertion_node(self, node: n.Parent[n.Node]) -> Optional[n.Node]:
+        """Search via BFS for the first 'section' from a root node, arbitrarily terminating early if
+        no 'section' is found within the first 50 nodes."""
+        queue: List[n.Node] = list(node.children)
+        curr_iteration = 0
+        max_iteration = 50
+
+        insertion_node = None
+
+        while queue and curr_iteration < max_iteration:
+            candidate = queue.pop(0)
+            if candidate.type == "section":
+                insertion_node = candidate
+                break
+            if isinstance(candidate, n.Parent):
+                queue.extend(candidate.children)
+
+            curr_iteration += 1
+        return insertion_node
+
+    def __determine_banner_index(self, node: n.Parent[n.Node]) -> int:
+        """Determine if there's a heading within the first level of the target insertion node's children.
+        If so, return the index position after the first detected heading. Otherwise, return 0."""
+        return (
+            next(
+                (
+                    idx
+                    for idx, child in enumerate(node.children)
+                    if isinstance(child, n.Heading)
+                ),
+                0,
+            )
+            + 1
+        )
+
+    def __page_target_match(
+        self, targets: List[str], page: Page, fileid: FileId
+    ) -> bool:
+        """Check if page matches target specified, but assert to ensure this does not run on includes"""
+        assert fileid.suffix == ".txt"
+
+        page_path_relative_to_source = page.source_path.relative_to(
+            self.root / "source"
+        )
+
+        for target in targets:
+            if page_path_relative_to_source.match(target):
+                return True
+        return False
+
+    def __call__(self, fileid_stack: FileIdStack, page: Page) -> None:
+        """Attach a banner as specified throughout project for target pages"""
+        for banner in self.banners:
+            if not self.__page_target_match(banner.targets, page, fileid_stack.current):
+                continue
+
+            banner_parent = self.__find_target_insertion_node(page.ast)
+            if isinstance(banner_parent, n.Parent):
+                target_insertion = self.__determine_banner_index(banner_parent)
+                assert banner_parent is not None
+                banner_parent.children.insert(
+                    target_insertion, util.fast_deep_copy(banner.node)
+                )
+
+
 class IAHandler:
     """Identify IA directive on a page and save a list of its entries as a page-level option."""
 
@@ -714,6 +788,9 @@ def run(
         tabs_selector_handler = TabsSelectorHandler(self.diagnostics)
         contents_handler = ContentsHandler(self.diagnostics)
         self.heading_handler = HeadingHandler(self.targets)
+        banner_handler = BannerHandler(
+            self.project_config.banner_nodes, self.project_config.root
+        )
 
         self.run_event_parser(
             [
@@ -732,6 +809,7 @@ def run(
                 (EventParser.PAGE_START_EVENT, option_handler.reset),
                 (EventParser.PAGE_START_EVENT, tabs_selector_handler.reset),
                 (EventParser.PAGE_START_EVENT, contents_handler.reset),
+                (EventParser.PAGE_START_EVENT, banner_handler),
                 (EventParser.PAGE_END_EVENT, contents_handler.finalize_headings),
                 (EventParser.PAGE_END_EVENT, tabs_selector_handler.finalize_tabsets),
                 (EventParser.PAGE_END_EVENT, self.heading_handler.reset),
@@ -1365,7 +1443,6 @@ def clean_and_validate_page_group_slug(slug: str) -> Optional[str]:
 
         if page_groups:
             document.update({"pageGroups": page_groups})
-
         return document, self.diagnostics
 
     def reset_query_fields(self, fileid_stack: FileIdStack, page: Page) -> None:

snooty/rstspec.toml

@@ -4,6 +4,7 @@ version = 0
 [enum]
 alignment = ["left", "center", "right"]
 backlinks = ["entry", "top", "none"]
+banner_variant = ["info", "warning", "danger"]
 card_layout = ["default", "carousel"]
 card_style = ["default", "compact", "extra-compact"]
 card_type = ["small", "large"]
@@ -614,6 +615,16 @@ content_type = "block"
 # """
 
 ##### Internal "mongodb" directives
+[directive."mongodb:banner"]
+help = """A skinny admonition, meant for alerts or smaller notifications."""
+content_type = "block"
+options.variant = "banner_variant"
+example = """.. banner::
+   :variant: ${1: warning (Optional)}
+
+   ${2:banner content}
+"""
+
 [directive."mongodb:button"]
 help = "Make a button."
 example = """.. button:: ${1: string}

snooty/test_parser.py

@@ -784,6 +784,34 @@ def test_admonition_deprecated() -> None:
     )
 
 
+def test_banner() -> 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,
+        """
+.. banner:: 
+    :variant: warning
+
+    Content
+""",
+    )
+    page.finish(diagnostics)
+    assert diagnostics == []
+    print(page.ast)
+    check_ast_testing_string(
+        page.ast,
+        """<root fileid="test.rst">
+        <directive domain="mongodb" name="banner" variant="warning">
+            <paragraph><text>Content</text></paragraph>
+        </directive>
+        </root>""",
+    )
+
+
 def test_rst_replacement() -> None:
     path = ROOT_PATH.joinpath(Path("test.rst"))
     project_config = ProjectConfig(ROOT_PATH, "", source="./")