On Wed, Mar 5, 2025, 4:13 AM Markus Armbruster <arm...@redhat.com> wrote:
> John Snow <js...@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 <harmo...@gmail.com>
> > Signed-off-by: John Snow <js...@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.
>
Almost certifiably a Sphinx version difference that I simply won't be able
to accommodate. It comes back clean against 8.x, and does not impact the
runtime functionality at all.
> > + 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.
>
>
