John Snow <[email protected]> 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 <[email protected]>
> Signed-off-by: John Snow <[email protected]>
[...]
> 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.
