[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH 19/27] docs/qapi-domain: add :unstable: directive option
From: |
John Snow |
Subject: |
[PATCH 19/27] docs/qapi-domain: add :unstable: directive option |
Date: |
Fri, 19 Apr 2024 00:38:07 -0400 |
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 <harmonie@gmail.com>
Signed-off-by: John Snow <jsnow@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
- [PATCH 06/27] docs/qapi-domain: add QAPI xref roles, (continued)
- [PATCH 06/27] docs/qapi-domain: add QAPI xref roles, John Snow, 2024/04/19
- [PATCH 05/27] docs/qapi-domain: add resolve_any_xref(), John Snow, 2024/04/19
- [PATCH 07/27] docs/qapi-domain: add qapi:command directive, John Snow, 2024/04/19
- [PATCH 08/27] docs/qapi-domain: add :since: directive option, John Snow, 2024/04/19
- [PATCH 09/27] docs/qapi-domain: add "Arguments:" field lists, John Snow, 2024/04/19
- [PATCH 11/27] docs/qapi-domain: add "Errors:" field lists, John Snow, 2024/04/19
- [PATCH 02/27] docs/qapi-domain: add qapi:module directive, John Snow, 2024/04/19
- [PATCH 12/27] docs/qapi-domain: add "Returns:" field lists, John Snow, 2024/04/19
- [PATCH 14/27] docs/qapi-domain: add qapi:alternate directive, John Snow, 2024/04/19
- [PATCH 18/27] docs/qapi-domain: add :deprecated: directive option, John Snow, 2024/04/19
- [PATCH 19/27] docs/qapi-domain: add :unstable: directive option,
John Snow <=
- [PATCH 20/27] docs/qapi-domain: add :ifcond: directive option, John Snow, 2024/04/19
- [PATCH 25/27] docs/qapi-domain: implement error context reporting fix, John Snow, 2024/04/19
- [PATCH 26/27] docs/qapi-domain: RFC patch - Add one last sample command, John Snow, 2024/04/19
- [PATCH 27/27] docs/qapi-domain: add CSS styling, John Snow, 2024/04/19
- [PATCH 24/27] docs/qapi-domain: add type cross-refs to field lists, John Snow, 2024/04/19
- Re: [PATCH 00/27] Add qapi-domain Sphinx extension, Markus Armbruster, 2024/04/19