docs/sphinx/qapidoc.py

1 # coding=utf-8
5 # Copyright (c) 2024-2025 Red Hat
9 # See the COPYING file in the top-level directory.
12 qapidoc is a Sphinx extension that implements the qapi-doc directive
17 It implements one new rST directive, "qapi-doc::".
18 Each qapi-doc:: directive takes one argument, which is the
21 The docs/conf.py file must set the qapidoc_srctree config value to
25 https://www.sphinx-doc.org/en/master/development/index.html
88     # pylint: disable=too-many-public-methods
100     def __init__(self) -> None:
106     def result(self) -> StringList:
110     def entity(self) -> QAPISchemaDefinition:
115     def member_field_type(self) -> str:
118     # General-purpose rST generation functions
120     def get_indent(self) -> str:
124     def indented(self) -> Generator[None]:
129             self.indent -= 1
131     def add_line_raw(self, line: str, source: str, *lineno: int) -> None:
134         # NB: Sphinx uses zero-indexed lines; subtract one.
135         lineno = tuple((n - 1 for n in lineno))
145     def add_line(self, content: str, info: QAPISourceInfo) -> None:
147         # don't document built-in objects that don't have
149         self.add_line_raw(content, info.fname, info.line)
153         content: str,
155     ) -> None:
156         lines = content.splitlines(True)
160     def ensure_blank_line(self) -> None:
161         # Empty document -- no blank line required.
166         if self._result[-1].strip():  # pylint: disable=no-member
167             fname, line = self._result.info(-1)
169             # New blank line is credited to one-after the current last line.
180     ) -> None:
189     ) -> Optional[str]:
217     ) -> None:
223     def visit_paragraph(self, section: QAPIDoc.Section) -> None:
232     def visit_member(self, section: QAPIDoc.ArgSection) -> None:
234         # TODO: features for members (documented at entity-level,
235         # but sometimes defined per-member. Should we add such
246     def visit_feature(self, section: QAPIDoc.ArgSection) -> None:
247         # FIXME - ifcond for features is not handled at all yet!
248         # Proposal: decorate the right-hand column with some graphical
255     def visit_returns(self, section: QAPIDoc.Section) -> None:
269     def visit_errors(self, section: QAPIDoc.Section) -> None:
275     def preamble(self, ent: QAPISchemaDefinition) -> None:
292         # special features are added, qapi-domain will chirp about
294         # qapi-domain.
305     def _insert_member_pointer(self, ent: QAPISchemaDefinition) -> None:
309         ) -> Optional[QAPISchemaDefinition]:
342     def visit_sections(self, ent: QAPISchemaDefinition) -> None:
361             section.text = re.sub(r"@([\w-]+)", r"``\1``", section.text)
382             if i == gen_index - 1:
389     def visit_module(self, path: str) -> None:
395     def visit_freeform(self, doc: QAPIDoc) -> None:
399         # For now, translate our micro-format into rST. Code adapted
415             # https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections
431             info = info.next_line(len(text) - len(trimmed) + 1)
436     def visit_entity(self, ent: QAPISchemaDefinition) -> None:
455     def set_namespace(self, namespace: str, source: str, lineno: int) -> None:
470     def __init__(self, env: Any, qapidir: str) -> None:
474     def visit_module(self, name: str) -> None:
482     def run(self) -> Sequence[nodes.Node]:
485     def do_parse(self, rstlist: StringList, node: nodes.Node) -> None:
511     def new_serialno(self) -> str:
514         return "qapidoc-%d" % env.new_serialno("qapidoc")
516     def transmogrify(self, schema: QAPISchema) -> nodes.Element:
519         modules = set()
542         content = vis.result
546         with switch_source_input(self.state, content):
550                 nested_parse_with_titles(self.state, content, contentnode)
554                 self.state.nested_parse(content, 0, contentnode)
560             self.write_intermediate(content, name)
565     def write_intermediate(self, content: StringList, filename: str) -> None:
576         for i, line in enumerate(content):
577             src, lineno = content.info(i)
585         with open(filename, "w", encoding="UTF-8") as outfile:
593     def legacy(self, schema: QAPISchema) -> nodes.Element:
603     def run(self) -> Sequence[nodes.Node]:
633     is parsed as normal rST, but with any '::' code blocks set to use
650     def _highlightlang(self) -> addnodes.highlightlang:
672             # numbers and not 0 or None or -1 or something. ¯\_(ツ)_/¯
677     def admonition_wrap(self, *content: nodes.Node) -> List[nodes.Node]:
685             *content,
686             classes=["admonition", "admonition-example"],
690     def run_annotated(self) -> List[nodes.Node]:
703         self.do_parse(self.content, content_node)
711     def run(self) -> List[nodes.Node]:
723 def setup(app: Sphinx) -> ExtensionMetadata:
724     """Register qapi-doc directive with Sphinx"""
727     app.add_directive("qapi-doc", QAPIDocDirective)
728     app.add_directive("qmp-example", QMPExample)