From ecf92e3618ab6e6cd7ae151f9c12b9e2a6ead198 Mon Sep 17 00:00:00 2001 From: John Snow Date: Mon, 10 Mar 2025 23:42:01 -0400 Subject: docs/sphinx: create QAPI domain extension stub A Sphinx domain is a collection of directive and role extensions meant to facilitate the documentation of a specific language. For instance, Sphinx ships with "python" and "cpp" domains. This patch introduces a stub for the "qapi" language domain. Please see https://www.sphinx-doc.org/en/master/usage/domains/index.html for more information. This stub doesn't really do anything yet, we'll get to it brick-by-brick in the forthcoming commits to keep the series breezy and the git history informative. Signed-off-by: John Snow Message-ID: <20250311034303.75779-4-jsnow@redhat.com> Acked-by: Markus Armbruster Signed-off-by: Markus Armbruster --- docs/sphinx/qapi_domain.py | 56 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 docs/sphinx/qapi_domain.py (limited to 'docs/sphinx/qapi_domain.py') diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py new file mode 100644 index 0000000000..a1983d9444 --- /dev/null +++ b/docs/sphinx/qapi_domain.py @@ -0,0 +1,56 @@ +""" +QAPI domain extension. +""" + +from __future__ import annotations + +from typing import ( + TYPE_CHECKING, + AbstractSet, + Any, + Dict, + Tuple, +) + +from sphinx.domains import Domain, ObjType +from sphinx.util import logging + + +if TYPE_CHECKING: + from sphinx.application import Sphinx + +logger = logging.getLogger(__name__) + + +class QAPIDomain(Domain): + """QAPI language domain.""" + + name = "qapi" + label = "QAPI" + + object_types: Dict[str, ObjType] = {} + directives = {} + roles = {} + initial_data: Dict[str, Dict[str, Tuple[Any]]] = {} + indices = [] + + def merge_domaindata( + self, docnames: AbstractSet[str], otherdata: Dict[str, Any] + ) -> None: + pass + + def resolve_any_xref(self, *args: Any, **kwargs: Any) -> Any: + # pylint: disable=unused-argument + return [] + + +def setup(app: Sphinx) -> Dict[str, Any]: + app.setup_extension("sphinx.directives") + app.add_domain(QAPIDomain) + + return { + "version": "1.0", + "env_version": 1, + "parallel_read_safe": True, + "parallel_write_safe": True, + } -- cgit 1.4.1