[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH 08/27] docs/qapi-domain: add :since: directive option
From: |
John Snow |
Subject: |
[PATCH 08/27] docs/qapi-domain: add :since: directive option |
Date: |
Fri, 19 Apr 2024 00:37:56 -0400 |
Add a little special markup for registering "Since:" information. Adding
it as an option instead of generic content lets us hoist the information
into the Signature bar, optionally put it in the index, etc.
Signed-off-by: John Snow <jsnow@redhat.com>
---
docs/qapi/index.rst | 1 +
docs/sphinx/qapi-domain.py | 27 +++++++++++++++++++++++++--
2 files changed, 26 insertions(+), 2 deletions(-)
diff --git a/docs/qapi/index.rst b/docs/qapi/index.rst
index 5516f762a24..33b9349a3ee 100644
--- a/docs/qapi/index.rst
+++ b/docs/qapi/index.rst
@@ -54,6 +54,7 @@ Explicit cross-referencing syntax for QAPI modules is
available with
.. qapi:command:: example-command
+ :since: 42.0
This directive creates a QAPI command named `example-command` that
appears in both the `genindex` and the `qapi-index`. As of this
diff --git a/docs/sphinx/qapi-domain.py b/docs/sphinx/qapi-domain.py
index 2c1e60290d9..38a50318d08 100644
--- a/docs/sphinx/qapi-domain.py
+++ b/docs/sphinx/qapi-domain.py
@@ -4,6 +4,7 @@
from __future__ import annotations
+import re
from typing import (
TYPE_CHECKING,
Any,
@@ -86,6 +87,18 @@ def process_link(
return title, target
+def since_validator(param: str) -> str:
+ """
+ Validate the `:since: X.Y` option field.
+ """
+ match = re.match(r"[0-9]+\.[0-9]+", param)
+ if not match:
+ raise ValueError(
+ f":since: requires a version number in X.Y format; not {param!r}"
+ )
+ return param
+
+
def _nested_parse(directive: SphinxDirective, content_node: Element) -> None:
"""
This helper preserves error parsing context across sphinx versions.
@@ -127,6 +140,8 @@ class QAPIObject(ObjectDescription[Signature]):
{
# Borrowed from the Python domain:
"module": directives.unchanged, # Override contextual module name
+ # These are QAPI originals:
+ "since": since_validator,
}
)
@@ -138,9 +153,17 @@ def get_signature_prefix(self, sig: str) ->
List[nodes.Node]:
addnodes.desc_sig_space(),
]
- def get_signature_suffix(self, sig: str) -> list[nodes.Node]:
+ def get_signature_suffix(self, sig: str) -> List[nodes.Node]:
"""Returns a suffix to put after the object name in the signature."""
- return []
+ ret: List[nodes.Node] = []
+
+ if "since" in self.options:
+ ret += [
+ addnodes.desc_sig_space(),
+ addnodes.desc_sig_element("", f"(Since:
{self.options['since']})"),
+ ]
+
+ return ret
def handle_signature(self, sig: str, signode: desc_signature) -> Signature:
"""
--
2.44.0
- [PATCH 13/27] docs/qapi-domain: add qapi:enum directive, (continued)
- [PATCH 13/27] docs/qapi-domain: add qapi:enum directive, John Snow, 2024/04/19
- [PATCH 16/27] docs/qapi-domain: add qapi:struct directive, John Snow, 2024/04/19
- [PATCH 15/27] docs/qapi-domain: add qapi:event directive, John Snow, 2024/04/19
- [PATCH 22/27] docs/qapi-domain: add warnings for malformed field lists, John Snow, 2024/04/19
- [PATCH 17/27] docs/qapi-domain: add qapi:union and qapi:branch directives, John Snow, 2024/04/19
- [PATCH 23/27] docs/qapi-domain: RFC patch - delete malformed field lists, John Snow, 2024/04/19
- [PATCH 21/27] docs/qapi-domain: RFC patch - add malformed field list entries, John Snow, 2024/04/19
- [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 <=
- [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, 2024/04/19
- [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