[PATCH 30/42] docs/qapidoc: add minimalistic inliner

[John Snow <jsnow@redhat.com>]

Add a minimalistic inliner that only gets the basics - leaving branch
inlining for a future patch.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 docs/sphinx/qapidoc.py | 174 ++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 172 insertions(+), 2 deletions(-)

diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index 154ebc1b4cd..538c26e812d 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -25,13 +25,15 @@
 https://www.sphinx-doc.org/en/master/development/index.html
 """
 
+from collections import defaultdict
 from contextlib import contextmanager
+import enum
 import os
 from pathlib import Path
 import re
 import sys
 import textwrap
-from typing import List, Optional
+from typing import Dict, List, Optional
 
 from docutils import nodes
 from docutils.parsers.rst import Directive, directives
@@ -45,8 +47,10 @@
     QAPISchemaCommand,
     QAPISchemaEntity,
     QAPISchemaEnumMember,
+    QAPISchemaEvent,
     QAPISchemaFeature,
     QAPISchemaMember,
+    QAPISchemaObjectType,
     QAPISchemaObjectTypeMember,
 )
 from qapi.source import QAPISourceInfo
@@ -77,6 +81,172 @@ def dedent(text: str) -> str:
     return lines[0] + textwrap.dedent("".join(lines[1:]))
 
 
+class DocRegion(enum.Enum):
+    # The inliner introduces the concept of doc Regions, which are
+    # groupings of zero or more Sections. These regions are used to know
+    # how to combine two lists of Sections.
+    INTRO = 0
+    MEMBER = 1
+    OTHER = 2
+    FEATURE = 3
+    DETAIL = 4
+
+    @staticmethod
+    def categorize(section: QAPIDoc.Section) -> "Optional[DocRegion]":
+        return MAPPING[section.kind]
+
+
+MAPPING = {
+    QAPIDoc.Kind.INTRO: DocRegion.INTRO,
+    QAPIDoc.Kind.MEMBER: DocRegion.MEMBER,
+    QAPIDoc.Kind.FEATURE: DocRegion.FEATURE,
+    QAPIDoc.Kind.RETURNS: DocRegion.OTHER,
+    QAPIDoc.Kind.ERRORS: DocRegion.OTHER,
+    QAPIDoc.Kind.SINCE: None,
+    QAPIDoc.Kind.TODO: None,
+    QAPIDoc.Kind.DETAIL: DocRegion.DETAIL,
+}
+
+
+class InlinerSections:
+
+    def __init__(self, sections):
+        self._sections: List[QAPIDoc.Section] = list(sections)
+        self.partitions: Dict[DocRegion, List[QAPIDoc.Section]] = defaultdict(
+            list
+        )
+        self._modified = False
+
+        self._partition()
+
+    def _partition(self):
+        for section in self._sections:
+            # suppress empty text sections for the purpose of, later,
+            # being able to determine if a collection of doc sections
+            # "has an intro" or "has a details section" or not, which is
+            # helpful later on for some assertions about the inliner.
+            if section.kind in (QAPIDoc.Kind.INTRO, QAPIDoc.Kind.DETAIL):
+                if not section.text:
+                    continue
+
+            region = DocRegion.categorize(section)
+            if region is None:
+                continue
+
+            self.partitions[region].append(section)
+
+    def absorb(self, other: "InlinerSections"):
+        for category, oval in other.partitions.items():
+            val = self.partitions[category]
+            if category == DocRegion.INTRO:
+                # The intro region is not inlined, it is dropped.
+                continue
+
+            # Everything else is prepended.
+            self.partitions[category] = oval + val
+            if oval:
+                self._modified = True
+
+    def __iter__(self):
+        return iter(self._flatten())
+
+    def _flatten(self):
+        # Serialize back into a normal list.
+
+        # If nothing has changed, we don't need to do anything.
+        if not self._modified:
+            return tuple(self._sections)
+
+        # Otherwise, we need to rebuild the sequence.
+        #
+        # FIXME: This function assumes a stricter ordering of regions
+        # within the source docs (see DocRegion); This order is not
+        # currently enforced in parser.py, so this method may shift some
+        # contents around compared to the source.
+        tmp = []
+        for category in DocRegion:
+            tmp.extend(self.partitions[category])
+        self._sections = tmp
+        self._modified = False
+        return tuple(self._sections)
+
+
+def inline(ent: QAPISchemaEntity) -> List[QAPIDoc.Section]:
+    """
+    Return all of an entity's doc sections with inlined sections stitched in.
+
+    First, a given entity's sections are retrieved in full, in source order.
+
+    Next, if this entity has either an argument type (Commands and
+    Events) or an inherited base (Structs, Unions), this function is
+    called recursively on that type to retrieve its sections. These
+    sections are then stitched into the result.
+
+    Lastly, if this entity has any branches, this function is called
+    recursively on each branch type and those sections are stitched into
+    the result.
+
+    STITCH ORDER:
+
+      - Introduction
+      - [Inlined introduction sections are dropped.]
+      - Recursively inlined Members
+      - Members
+      - Recursively inlined Branch members
+      - Other special sections (Errors, Returns)
+      - [There are no cases where we have these sections to inline.]
+      - Recursively inlined Features
+      - Features
+      - Recursively inlined Details
+      - Details
+
+    Intro paragraphs are never stitched into the documentation section
+    list. Members, Features, and Details paragraphs are stitched in
+    *before* the given entity's equivalent regions. Individual sections
+    otherwise appear in source order as they do in the parent or child.
+
+    Branch members are stitched in *after* the member section.
+
+    In the event that a paragraph cannot be determined to be an intro or
+    details type, a warning is emitted. It will be treated as an intro
+    section and dropped from the output. QEMU usually treats Sphinx
+    warnings as fatal, so this warning is usually fatal.
+    """
+
+    def _sections(ent) -> List[QAPIDoc.Section]:
+        return ent.doc.all_sections if ent.doc else []
+
+    def _get_inline_target(
+        ent: QAPISchemaEntity,
+    ) -> Optional[QAPISchemaEntity]:
+        """Get the entity to inline from for a given entity."""
+        if isinstance(ent, (QAPISchemaCommand, QAPISchemaEvent)):
+            return ent.arg_type
+        if isinstance(ent, QAPISchemaObjectType):
+            return ent.base
+        return None
+
+    # Let's do this thing!
+
+    if ent is None:
+        return []
+
+    # Grab all directly documented sections for the entity in question.
+    sections = InlinerSections(_sections(ent))
+
+    # Get inlined sections: this includes everything from the
+    # inlined entity (and anything it inlines, too).
+    inlined = InlinerSections(inline(_get_inline_target(ent)))
+
+    # Now, stitch the results together!
+    sections.absorb(inlined)
+
+    # FIXME: Branches should be handled about here O:-)
+
+    # Return the combined list of sections.
+    return list(sections)
+
+
 class Transmogrifier:
     # Field names used for different entity types:
     field_types = {
@@ -285,7 +455,7 @@ def preamble(self, ent: QAPISchemaEntity) -> None:
         self.ensure_blank_line()
 
     def visit_sections(self, ent: QAPISchemaEntity) -> None:
-        sections = ent.doc.all_sections if ent.doc else []
+        sections = inline(ent)
 
         # Add sections *in the order they are documented*:
         for section in sections:
-- 
2.48.1