DOP-2444: Add directives and metadata for guides (#349)

* DOP-2444: Add directives and metadata for guides

* Get chapters' guides in separate function

* Fix guide data serialization

* Apply feedback

* Remove context arg

Author: rayangler

snooty/diagnostics.py

@@ -618,11 +618,11 @@ class ChapterAlreadyExists(Diagnostic):
 
     def __init__(
         self,
-        chapterName: str,
+        chapter_name: str,
         start: Union[int, Tuple[int, int]],
         end: Union[None, int, Tuple[int, int]] = None,
     ) -> None:
-        super().__init__(f'Chapter "{chapterName}" already exists', start, end)
+        super().__init__(f'Chapter "{chapter_name}" already exists', start, end)
 
 
 class InvalidChapter(Diagnostic):
@@ -643,12 +643,30 @@ class MissingChild(Diagnostic):
     def __init__(
         self,
         directive: str,
-        expectedChild: str,
+        expected_child: str,
         start: Union[int, Tuple[int, int]],
         end: Union[None, int, Tuple[int, int]] = None,
     ) -> None:
         super().__init__(
-            f'Directive "{directive}" expects at least one child of type "{expectedChild}"; found 0',
+            f'Directive "{directive}" expects at least one child of type "{expected_child}"; found 0',
+            start,
+            end,
+        )
+
+
+class GuideAlreadyHasChapter(Diagnostic):
+    severity = Diagnostic.Level.error
+
+    def __init__(
+        self,
+        guide_slug: str,
+        assigned_chapter: str,
+        target_chapter: str,
+        start: Union[int, Tuple[int, int]],
+        end: Union[None, int, Tuple[int, int]] = None,
+    ) -> None:
+        super().__init__(
+            f"""Cannot add guide "{guide_slug}" to chapter "{target_chapter}" because the guide is already assigned to chapter "{assigned_chapter}\"""",
             start,
             end,
         )

snooty/postprocess.py

@@ -6,7 +6,7 @@
 import urllib.parse
 from collections import defaultdict
 from copy import deepcopy
-from dataclasses import asdict, dataclass
+from dataclasses import asdict, dataclass, field
 from typing import (
     Any,
     Callable,
@@ -33,6 +33,7 @@
     DuplicateDirective,
     ExpectedPathArg,
     ExpectedTabs,
+    GuideAlreadyHasChapter,
     InvalidChapter,
     InvalidChild,
     InvalidContextError,
@@ -723,19 +724,52 @@ class ChapterData:
         description: Optional[str]
         guides: List[str]
 
+    @dataclass
+    class GuideData:
+        chapter_name: str = ""
+        completion_time: int = 0
+        description: MutableSequence[n.Node] = field(default_factory=list)
+        title: Sequence[n.InlineNode] = field(default_factory=list)
+
+        def serialize(self) -> n.SerializedNode:
+            result: n.SerializedNode = {
+                "chapter_name": self.chapter_name,
+                "completion_time": self.completion_time,
+                "description": [node.serialize() for node in self.description],
+                "title": [node.serialize() for node in self.title],
+            }
+            return result
+
+    def add_guides_metadata(self, document: Dict[str, SerializableType]) -> None:
+        """Adds the guides-related metadata to the project's metadata document"""
+        if self.chapters:
+            document["chapters"] = {k: asdict(v) for k, v in self.chapters.items()}
+
+        if self.guides:
+            slug_title_mapping = self.context[HeadingHandler].slug_title_mapping
+            for slug, title in slug_title_mapping.items():
+                if slug in self.guides:
+                    self.guides[slug].title = title
+            document["guides"] = {k: v.serialize() for k, v in self.guides.items()}
+
     def __init__(self, context: Context) -> None:
         super().__init__(context)
         self.chapters: Dict[str, GuidesHandler.ChapterData] = {}
+        self.guides: Dict[str, GuidesHandler.GuideData] = defaultdict(
+            GuidesHandler.GuideData
+        )
 
-    def __handle_chapter(self, chapter: n.Directive, current_file: FileId) -> None:
-        """Saves a chapter's data into the handler's dictionary of chapters"""
+    def __get_guides(
+        self, chapter: n.Directive, chapter_title: str, current_file: FileId
+    ) -> List[str]:
+        """Returns the eligible guides that belong to a given chapter"""
 
         guides: List[str] = []
 
         for child in chapter.get_child_of_type(n.Directive):
+            line = child.span[0]
+
             if child.name != "guide":
-                # Chapter directives should contain only guide directives
-                line = chapter.span[0]
                 self.context.diagnostics[current_file].append(
                     InvalidChild(child.name, "chapter", "guide", line, None)
                 )
@@ -744,26 +778,40 @@ def __handle_chapter(self, chapter: n.Directive, current_file: FileId) -> None:
             guide_argument = child.argument
             if not guide_argument:
                 self.context.diagnostics[current_file].append(
-                    ExpectedPathArg(child.name, child.span[0])
+                    ExpectedPathArg(child.name, line)
                 )
                 continue
 
             guide_slug = clean_slug(guide_argument[0].get_text())
+
+            current_guide_data = self.guides[guide_slug]
+            if current_guide_data.chapter_name:
+                self.context.diagnostics[current_file].append(
+                    GuideAlreadyHasChapter(
+                        guide_slug,
+                        current_guide_data.chapter_name,
+                        chapter_title,
+                        line,
+                    )
+                )
+                continue
+            else:
+                current_guide_data.chapter_name = chapter_title
+
             guides.append(guide_slug)
 
-        line = chapter.span[0]
+        return guides
 
-        # A chapter should always have at least one guide
-        if not guides:
-            self.context.diagnostics[current_file].append(
-                MissingChild("chapter", "guide", line)
-            )
-            return
+    def __handle_chapter(self, chapter: n.Directive, current_file: FileId) -> None:
+        """Saves a chapter's data into the handler's dictionary of chapters"""
 
+        line = chapter.span[0]
         title_argument = chapter.argument
-        if not title_argument:
+        if len(title_argument) != 1:
             self.context.diagnostics[current_file].append(
-                InvalidChapter("Title argument is empty.", line)
+                InvalidChapter(
+                    "Invalid title argument. The title should be plain text.", line
+                )
             )
             return
 
@@ -781,6 +829,14 @@ def __handle_chapter(self, chapter: n.Directive, current_file: FileId) -> None:
         if not description:
             return
 
+        guides: List[str] = self.__get_guides(chapter, title, current_file)
+        # A chapter should always have at least one guide
+        if not guides:
+            self.context.diagnostics[current_file].append(
+                MissingChild("chapter", "guide", line)
+            )
+            return
+
         if not self.chapters.get(title):
             self.chapters[title] = GuidesHandler.ChapterData(
                 len(self.chapters) + 1, description, guides
@@ -824,17 +880,26 @@ def __handle_chapters(
             )
 
     def enter_node(self, fileid_stack: FileIdStack, node: n.Node) -> None:
+        if not isinstance(node, n.Directive):
+            return
+
         current_file: FileId = fileid_stack.current
+        current_slug = clean_slug(current_file.without_known_suffix)
 
-        if (
-            isinstance(node, n.Directive)
-            and node.name == "chapters"
-            and current_file.as_posix() == "index.txt"
-        ):
+        if node.name == "chapters" and current_file == FileId("index.txt"):
             if self.chapters:
                 return
-
             self.__handle_chapters(node, current_file)
+        elif node.name == "time":
+            if not node.argument:
+                return
+            try:
+                completion_time = int(node.argument[0].get_text())
+                self.guides[current_slug].completion_time = completion_time
+            except ValueError:
+                pass
+        elif node.name == "short-description":
+            self.guides[current_slug].description = node.children
 
 
 class IAHandler(Handler):
@@ -1391,9 +1456,7 @@ def generate_metadata(cls, context: Context) -> n.SerializedNode:
         if iatree:
             document["iatree"] = iatree
 
-        chapters = context[GuidesHandler].chapters
-        if chapters:
-            document["chapters"] = {k: asdict(v) for k, v in chapters.items()}
+        context[GuidesHandler].add_guides_metadata(document)
 
         return document
 

snooty/rstspec.toml

@@ -719,6 +719,14 @@ example = """.. guide:: ${0: /path/to/guide.txt}"""
 argument_type = ["path", "uri"]
 content_type = "string"
 
+[directive."mongodb:guide-next"]
+help = "A section that directs users to what they should do next after reading a guide"
+example = """.. guide-next:: ${0: string}
+   ${1: content}
+"""
+argument_type = "string"
+content_type = "block"
+
 [directive."mongodb:introduction"]
 content_type = "block"
 
@@ -773,13 +781,25 @@ example = """ .. quizchoice:: ${1:string}
 argument_type = "string"
 options.is-true = "flag"
 
+[directive."mongodb:short-description"]
+help = "A description or preview of what the content will be about."
+content_type = "block"
+example = """.. short-description::
+   ${0: content}
+"""
+
 [directive."mongodb:step"]
 help = "Make a single, numbered step."
 example = """.. step:: ${0: Step's headline string}
 ${1: Step content}"""
 argument_type = "string"
 content_type = "block"
 
+[directive."mongodb:time"]
+help = "The amount of time that it would take to go through the guide content in minutes."
+argument_type = {type = "nonnegative_integer", required = true}
+example = """.. time:: 15"""
+
 ###### Misc.
 [directive.atf-image]
 help = "Path to the image to use for the above-the-fold header image"

snooty/test_postprocess.py

@@ -10,6 +10,7 @@
     DocUtilsParseError,
     DuplicateDirective,
     ExpectedTabs,
+    GuideAlreadyHasChapter,
     InvalidChapter,
     InvalidChild,
     InvalidContextError,
@@ -149,7 +150,7 @@ def test_ia() -> None:
         )
 
 
-def test_chapters() -> None:
+def test_guides() -> None:
     # Chapters are generated properly and page ast should look as expected
     with make_test(
         {
@@ -235,6 +236,51 @@ def test_chapters() -> None:
         assert chapters["CRUD"]["guides"] == ["path/to/guide3"]
         assert chapters["CRUD"]["chapter_number"] == 2
 
+    # Guides metadata is added to the project's metadata document
+    with make_test(
+        {
+            Path(
+                "source/index.txt"
+            ): """
+======
+Guides
+======
+
+.. chapters::
+
+    .. chapter:: Atlas
+        :description: This is the description for the Atlas chapter.
+        :image: /images/atlas.png
+
+        .. guide:: /path/to/guide1.txt
+            """,
+            Path(
+                "source/path/to/guide1.txt"
+            ): """
+=======
+Guide 1
+=======
+
+.. time:: 20
+.. short-description::
+
+   This is guide 1.
+            """,
+        }
+    ) as result:
+        assert not [
+            diagnostics for diagnostics in result.diagnostics.values() if diagnostics
+        ]
+        guides = cast(Dict[str, Any], result.metadata["guides"])
+        assert len(guides) == 1
+
+        test_guide_data = guides["path/to/guide1"]
+        assert test_guide_data["completion_time"] == 20
+        assert test_guide_data["title"][0]["value"] == "Guide 1"
+        test_guide_description = test_guide_data["description"][0]["children"][0]
+        assert test_guide_description["value"] == "This is guide 1."
+        assert test_guide_data["chapter_name"] == "Atlas"
+
     # Diagnostic errors reported
     with make_test(
         {
@@ -321,14 +367,39 @@ def test_chapters() -> None:
    .. chapter:: Test
       :description: This is a chapter
 
-      .. guide:: /path/to/guide1.txt
+      .. guide:: /path/to/guide2.txt
             """,
         }
     ) as result:
         diagnostics = result.diagnostics[FileId("index.txt")]
         assert len(diagnostics) == 1
         assert isinstance(diagnostics[0], ChapterAlreadyExists)
 
+    # Test adding 1 guide to multiple children
+    with make_test(
+        {
+            Path(
+                "source/index.txt"
+            ): """
+.. chapters::
+
+   .. chapter:: Test
+      :description: This is a chapter
+
+      .. guide:: /path/to/guide1.txt
+   
+   .. chapter:: Test: The Sequel
+      :description: This is another chapter
+
+      .. guide:: /path/to/guide1.txt
+      .. guide:: /path/to/guide2.txt
+            """,
+        }
+    ) as result:
+        diagnostics = result.diagnostics[FileId("index.txt")]
+        assert len(diagnostics) == 1
+        assert isinstance(diagnostics[0], GuideAlreadyHasChapter)
+
 
 # ensure that broken links still generate titles
 def test_broken_link() -> None: