(DOP-2320) Add tocicon page-level option to toctree_node (#367)

* (DOP-2320) add tocicon page-level option to toctree_node

* alter ast attribute definition

* reformat code

* fix tests

* Make tocicon option a string, add tests

Co-authored-by: Grace Chong <[email protected]>

Author: gjchong25

snooty/page.py

@@ -28,7 +28,7 @@ class Page:
     source_path: Path
     output_filename: str
     source: str
-    ast: n.Parent[n.Node]
+    ast: n.Root
     static_assets: Set[StaticAsset] = field(default_factory=set)
     pending_tasks: List[PendingTask] = field(default_factory=list)
     category: Optional[str] = None
@@ -40,7 +40,7 @@ def create(
         source_path: Path,
         output_filename: Optional[str],
         source: str,
-        ast: Optional[n.Parent[n.Node]] = None,
+        ast: Optional[n.Root] = None,
     ) -> "Page":
         if output_filename is None:
             output_filename = source_path.name

snooty/parser.py

@@ -997,7 +997,7 @@ def parse_rst(
     visitor, text = parser.parse(path, text)
 
     top_of_state = visitor.state[-1]
-    assert isinstance(top_of_state, n.Parent)
+    assert isinstance(top_of_state, n.Root)
     page = Page.create(path, None, text, top_of_state)
     page.static_assets = visitor.static_assets
     page.pending_tasks = visitor.pending

snooty/postprocess.py

@@ -1688,11 +1688,22 @@ def find_toctree_nodes(
                             else None
                         )
 
+                    toctree_node_options: Dict[str, Any] = {
+                        "drawer": slug not in toc_landing_pages
+                    }
+
+                    # Check if tocicon is a page level option
+                    if context.pages[FileId(slug_fileid)].ast.options:
+                        if "tocicon" in context.pages[FileId(slug_fileid)].ast.options:
+                            toctree_node_options["tocicon"] = context.pages[
+                                FileId(slug_fileid)
+                            ].ast.options["tocicon"]
+
                     toctree_node = {
                         "title": title,
                         "slug": "/" if slug == "index" else slug,
                         "children": [],
-                        "options": {"drawer": slug not in toc_landing_pages},
+                        "options": toctree_node_options,
                     }
 
                     # Don't recurse on the index page

snooty/test_postprocess.py

@@ -453,6 +453,76 @@ def test_broken_link() -> None:
         )
 
 
+# Test for toctree icon
+def test_tocicon() -> None:
+    with make_test(
+        {
+            Path(
+                "source/index.txt"
+            ): """
+:tocicon: sync
+
+=============================
+Collections :icon:`sync-pill`
+=============================
+            """
+        }
+    ) as result:
+        page = result.pages[FileId("index.txt")]
+        check_ast_testing_string(
+            page.ast,
+            """
+<root fileid="index.txt" tocicon="sync">
+    <section>
+        <heading id="collections">
+            <text>Collections </text>
+            <role name="icon" target="sync-pill"></role>
+        </heading>
+    </section>
+</root>
+""",
+        )
+
+
+def test_toctree_tocicon() -> None:
+    with make_test(
+        {
+            Path(
+                "source/install.txt"
+            ): """
+:tocicon: sync
+
+=============================
+Collections :icon:`sync-pill`
+=============================
+            """,
+            Path(
+                "source/index.txt"
+            ): """
+.. toctree::
+   :titlesonly:
+
+   Overview </index>
+   /install
+            """,
+        }
+    ) as result:
+        check_toctree_testing_string(
+            result.metadata["toctree"],
+            """
+<toctree slug="/">
+    <title><text>untitled</text></title>
+    <toctree slug="/" drawer="True">
+        <title><text>Overview</text></title>
+    </toctree>
+    <toctree slug="install" drawer="True" tocicon="sync">
+        <title><text>Collections </text><role name="icon" target="sync-pill"></role></title>
+    </toctree>
+</toctree>
+""",
+        )
+
+
 # Ensure that "index.txt" can add itself to the toctree
 def test_toctree_self_add() -> None:
     with make_test(
@@ -479,7 +549,7 @@ def test_toctree_self_add() -> None:
 <toctree slug="/">
     <title><text>untitled</text></title>
     <toctree slug="page1" drawer="True" />
-    <toctree slug="/" drawer="True">
+    <toctree slug="/" drawer="True" >
         <title><text>Overview</text></title>
     </toctree>
     <toctree slug="page2" drawer="True" />

snooty/test_postprocess_old_and_monolithic.py

@@ -234,7 +234,7 @@ def test_toctree(backend: Backend) -> None:
             <title><text>MongoDB Connector for Business Intelligence</text></title>
         </toctree>
         <toctree slug="page3" drawer="False" />
-        <toctree slug="page4" drawer="True">
+        <toctree slug="page4" drawer="True" >
             <title><text>Page Four</text></title>
         </toctree>
     </toctree>