Re: [PATCH 21/57] docs/qapi-domain: add :deprecated: directive option

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> Although "deprecated" is a feature (and *will* appear in the features
> list), add a special :deprecated: option to generate an eye-catch that
> makes this information very hard to miss.
>
> (The intent is to modify qapidoc.py to add this option whenever it
> detects that the features list attached to a definition contains the
> "deprecated" entry.)
>
> -
>
> RFC: Technically, this object-level option is un-needed and could be
> replaced with a standard content-level directive that e.g. qapidoc.py
> could insert at the beginning of the content block. I've done it here as
> an option to demonstrate how it would be possible to do.
>
> It's a matter of taste for "where" we feel like implementing it.
>
> One benefit of doing it this way is that we can create a single
> containing box to set CSS style options controlling the flow of multiple
> infoboxes. The other way to achieve that would be to create a directive
> that allows us to set multiple options instead, e.g.:
>
> .. qapi:infoboxes:: deprecated unstable
>
> or possibly:
>
> .. qapi:infoboxes::
>    :deprecated:
>    :unstable:
>
> For now, I've left these as top-level QAPI object options. "Hey, it works."
>
> P.S., I outsourced the CSS ;)
>
> Signed-off-by: Harmonie Snow <harmonie@gmail.com>
> Signed-off-by: John Snow <jsnow@redhat.com>

[...]

> diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py
> index fff5cca24cc..1be59e36bdf 100644
> --- a/docs/sphinx/qapi_domain.py
> +++ b/docs/sphinx/qapi_domain.py
> @@ -140,6 +140,7 @@ class QAPIObject(ObjectDescription[Signature]):
>              "module": directives.unchanged,  # Override contextual module name
>              # These are QAPI originals:
>              "since": since_validator,
> +            "deprecated": directives.flag,
>          }
>      )
>  
> @@ -253,6 +254,31 @@ def add_target_and_index(
>                      ("single", indextext, node_id, "", None)
>                  )
>  
> +    def _add_infopips(self, contentnode: addnodes.desc_content) -> None:
> +        # Add various eye-catches and things that go below the signature
> +        # bar, but precede the user-defined content.
> +        infopips = nodes.container()
> +        infopips.attributes["classes"].append("qapi-infopips")
> +
> +        def _add_pip(source: str, content: str, classname: str) -> None:
> +            node = nodes.container(source)
> +            node.append(nodes.Text(content))
> +            node.attributes["classes"].extend(["qapi-infopip", classname])
> +            infopips.append(node)
> +
> +        if "deprecated" in self.options:
> +            _add_pip(
> +                ":deprecated:",
> +                f"This {self.objtype} is deprecated.",
> +                "qapi-deprecated",
> +            )
> +
> +        if infopips.children:
> +            contentnode.insert(0, infopips)
> +
> +    def transform_content(self, content_node: addnodes.desc_content) -> None:

pylint warns:

    docs/sphinx/qapi_domain.py:279:4: W0237: Parameter 'contentnode' has been renamed to 'content_node' in overriding 'QAPIObject.transform_content' method (arguments-renamed)

For what it's worth, @content_node is easier on on my eyes than
@contentnode.

> +        self._add_infopips(content_node)
> +
>      def _toc_entry_name(self, sig_node: desc_signature) -> str:
>          # This controls the name in the TOC and on the sidebar.