DOP-3307: Generate metadata for OpenAPI content pages (#426)

snooty/parser.py

@@ -662,6 +662,7 @@ def handle_directive(
                     spec = json.dumps(safe_load(file_content))
                     spec_node = n.Text((line,), spec)
                     doc.children.append(spec_node)
+                    doc.options["source_type"] = "url"
                     return doc
                 except:
                     pass
@@ -672,6 +673,7 @@ def handle_directive(
                 return doc
 
             if uses_realm:
+                doc.options["source_type"] = "atlas"
                 return doc
 
             openapi_fileid, filepath = util.reroot_path(
@@ -710,6 +712,7 @@ def create_page() -> Tuple[Page, EmbeddedRstParser]:
                         spec = json.dumps(safe_load(f))
                         spec_node = n.Text((line,), spec)
                         doc.children.append(spec_node)
+                        doc.options["source_type"] = "local"
 
             except OSError as err:
                 self.diagnostics.append(

snooty/postprocess.py

@@ -919,6 +919,62 @@ def enter_node(self, fileid_stack: FileIdStack, node: n.Node) -> None:
             self.guides[current_slug].description = node.children
 
 
+class OpenAPIHandler(Handler):
+    """Constructs metadata for OpenAPI content pages."""
+
+    @dataclass
+    class SourceData:
+        source_type: str
+        source: str
+
+    def __init__(self, context: Context) -> None:
+        super().__init__(context)
+        self.openapi_pages: Dict[str, OpenAPIHandler.SourceData] = {}
+
+    def get_metadata(self) -> Dict[str, SerializableType]:
+        """Returns serialized object to be used as part of the build's metadata."""
+
+        return {k: asdict(v) for k, v in self.openapi_pages.items()}
+
+    def enter_node(self, fileid_stack: FileIdStack, node: n.Node) -> None:
+        if (
+            not isinstance(node, n.Directive)
+            or node.name != "openapi"
+            or node.options.get("preview")
+        ):
+            return
+
+        current_file = fileid_stack.current
+        current_slug = clean_slug(current_file.without_known_suffix)
+
+        if current_slug in self.openapi_pages:
+            self.context.diagnostics[current_file].append(
+                DuplicateDirective(node.name, node.start[0])
+            )
+            return
+
+        # source_type should be assigned in the parsing layer
+        source_type = node.options.get("source_type")
+        if not source_type:
+            return
+
+        source = ""
+        argument = node.argument[0]
+        # The parser determines the source_type based on the given argument and its
+        # node structure. We echo that logic here to grab the source without needing
+        # to worry about the argument's node structure.
+        # The source_type cannot be manually set in rST as long as the option is not exposed
+        # in the rstspec.
+        if source_type == "local" or source_type == "atlas":
+            assert isinstance(argument, n.Text)
+            source = argument.get_text()
+        else:
+            assert isinstance(argument, n.Reference)
+            source = argument.refuri
+
+        self.openapi_pages[current_slug] = self.SourceData(source_type, source)
+
+
 class IAHandler(Handler):
     """Identify IA directive on a page and save a list of its entries as a page-level option."""
 
@@ -1443,6 +1499,7 @@ class Postprocessor:
             ContentsHandler,
             BannerHandler,
             GuidesHandler,
+            OpenAPIHandler,
         ],
         [TargetHandler, IAHandler, NamedReferenceHandlerPass1],
         [RefsHandler, NamedReferenceHandlerPass2],
@@ -1541,6 +1598,10 @@ def generate_metadata(cls, context: Context) -> n.SerializedNode:
 
         context[GuidesHandler].add_guides_metadata(document)
 
+        openapi_pages_metadata = context[OpenAPIHandler].get_metadata()
+        if len(openapi_pages_metadata) > 0:
+            document["openapi_pages"] = openapi_pages_metadata
+
         manpages = build_manpages(context)
         document["static_files"] = manpages
 
@@ -1919,6 +1980,7 @@ class DevhubPostprocessor(Postprocessor):
             ContentsHandler,
             BannerHandler,
             GuidesHandler,
+            OpenAPIHandler,
         ],
         [TargetHandler, IAHandler, NamedReferenceHandlerPass1],
         [RefsHandler, NamedReferenceHandlerPass2, DevhubHandler],

snooty/rstspec.toml

@@ -836,6 +836,7 @@ help = """Include a reStructuredText file's contents."""
 argument_type = ["path", "string", "uri"]
 options.uses-rst = "flag"
 options.uses-realm = "flag"
+options.preview = "flag"
 
 [directive."mongodb:operation"]
 content_type = "block"