Re: [PATCH v3 07/16] qapi/docs: add "Intro" section

John Snow <[email protected]> writes:

> This patch adds an "Intro" doc section, intended to eventually replace
> the "Plain" doc section alongside a forthcoming "Details" section.
>
> For now, this section is not actually instantiated or used, but
> subsequent patches will slowly convert the leading introductory sections
> of QAPIDoc documentation to use this new section.
>
> A main motivation of this series of changes is to more explicitly
> delineate the "Introductory" documentation for each QAPI definition for
> the sake of the inliner. When inlining members, examples, and details
> from multiple QAPIDoc sections, we will want to omit the "Introductory"
> text from inlined definitions while keeping notes, caution boxes,
> examples, and so on. This new section facilitates that.
>
> Signed-off-by: John Snow <[email protected]>
> ---
>  docs/sphinx/qapidoc.py | 2 +-
>  scripts/qapi/parser.py | 3 ++-
>  2 files changed, 3 insertions(+), 2 deletions(-)
>
> diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
> index c2f09bac16c..1f7c15b7075 100644
> --- a/docs/sphinx/qapidoc.py
> +++ b/docs/sphinx/qapidoc.py
> @@ -368,7 +368,7 @@ def visit_sections(self, ent: QAPISchemaDefinition) -> None:
>          for i, section in enumerate(sections):
>              section.text = self.reformat_arobase(section.text)
>  
> -            if section.kind == QAPIDoc.Kind.PLAIN:
> +            if section.kind.name in ("PLAIN", "INTRO"):

Is the change from QAPIDoc.Kind.FOO to "FOO" just for brevity, or is
something going on I don't understand?

>                  self.visit_paragraph(section)
>              elif section.kind == QAPIDoc.Kind.MEMBER:
>                  assert isinstance(section, QAPIDoc.ArgSection)
> diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
> index d8068bb1bf6..97e7dacb0fd 100644
> --- a/scripts/qapi/parser.py
> +++ b/scripts/qapi/parser.py
> @@ -681,6 +681,7 @@ class Kind(enum.Enum):
>          ERRORS = 4
>          SINCE = 5
>          TODO = 6
> +        INTRO = 7
>  
>          @staticmethod
>          def from_string(kind: str) -> 'QAPIDoc.Kind':
> @@ -748,7 +749,7 @@ def has_features(self) -> bool:
>      def end(self) -> None:
>          for section in self.all_sections:
>              section.text = section.text.strip('\n')
> -            if section.kind != QAPIDoc.Kind.PLAIN and section.text == '':
> +            if not (section.kind.name in ("INTRO", "PLAIN") or section.text):
>                  raise QAPISemError(
>                      section.info, "text required after '%s:'" % section.kind)