Although "unstable" is a feature (and *will* appear in the features list), add a special :unstable: 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 "unstable" entry.) RFC: Same comments as last patch. Signed-off-by: Harmonie Snow <harmo...@gmail.com> Signed-off-by: John Snow <js...@redhat.com> --- docs/qapi/index.rst | 4 +++- docs/sphinx-static/theme_overrides.css | 6 +++++- docs/sphinx/qapi-domain.py | 8 ++++++++ 3 files changed, 16 insertions(+), 2 deletions(-) diff --git a/docs/qapi/index.rst b/docs/qapi/index.rst index b9a69f6bd17..6350791a3ed 100644 --- a/docs/qapi/index.rst +++ b/docs/qapi/index.rst @@ -96,13 +96,13 @@ Explicit cross-referencing syntax for QAPI modules is available with .. qapi:command:: fake-command :since: 13.37 :deprecated: + :unstable: This is a fake command, it's not real. It can't hurt you. :arg int foo: normal parameter documentation. :arg str bar: Another normal parameter description. :arg baz: Missing a type. - :feat unstable: More than unstable, this command doesn't even exist! :arg no-descr: :arg BitmapSyncMode discrim: How about branches in commands? @@ -120,6 +120,8 @@ Explicit cross-referencing syntax for QAPI modules is available with :feat deprecated: Although this command is fake, you should know that it's also deprecated. That's great news! Maybe it will go away and stop haunting you someday. + :feat unstable: This command, as a figment of your imagination, is + highly unstable and should not be relied upon. :error CommandNotFound: When you try to use this command, because it isn't real. :error GenericError: If the system decides it doesn't like the diff --git a/docs/sphinx-static/theme_overrides.css b/docs/sphinx-static/theme_overrides.css index 97b8c1c60e6..acdf11675db 100644 --- a/docs/sphinx-static/theme_overrides.css +++ b/docs/sphinx-static/theme_overrides.css @@ -172,7 +172,7 @@ div[class^="highlight"] pre { margin: 0.25em; } -.qapi-deprecated { +.qapi-deprecated,.qapi-unstable { background-color: #fffef5; border: solid #fff176 6px; font-weight: bold; @@ -181,6 +181,10 @@ div[class^="highlight"] pre { margin: 5px; } +.qapi-unstable::before { + content: '🚧 '; +} + .qapi-deprecated::before { content: '⚠️ '; } diff --git a/docs/sphinx/qapi-domain.py b/docs/sphinx/qapi-domain.py index 065ad501960..76157476e02 100644 --- a/docs/sphinx/qapi-domain.py +++ b/docs/sphinx/qapi-domain.py @@ -151,6 +151,7 @@ class QAPIObject(ObjectDescription[Signature]): # These are QAPI originals: "since": since_validator, "deprecated": directives.flag, + "unstable": directives.flag, } ) @@ -269,6 +270,13 @@ def _add_pip(source: str, content: str, classname: str) -> None: "qapi-deprecated", ) + if "unstable" in self.options: + _add_pip( + ":unstable:", + f"This {self.objtype} is unstable/experimental.", + "qapi-unstable", + ) + if infopips.children: contentnode.insert(0, infopips) -- 2.44.0