mirror of
https://gitlab.com/qemu-project/qemu
synced 2024-09-06 18:05:37 +00:00
![Marc-André Lureau](/assets/img/avatar_default.png)
Add a new dbus-doc directive to import D-Bus interfaces documentation from the introspection XML. The comments annotations follow the gtkdoc/kerneldoc style, and should be formatted with reST. Note: I realize after the fact that I was implementing those modules with sphinx 4, and that we have much lower requirements. Instead of lowering the features and code (removing type annotations etc), let's have a warning in the documentation when the D-Bus modules can't be used, and point to the source XML file in that case. Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com> Acked-by: Gerd Hoffmann <kraxel@redhat.com>
167 lines
5.2 KiB
Python
167 lines
5.2 KiB
Python
# D-Bus XML documentation extension
|
|
#
|
|
# Copyright (C) 2021, Red Hat Inc.
|
|
#
|
|
# SPDX-License-Identifier: LGPL-2.1-or-later
|
|
#
|
|
# Author: Marc-André Lureau <marcandre.lureau@redhat.com>
|
|
"""dbus-doc is a Sphinx extension that provides documentation from D-Bus XML."""
|
|
|
|
import os
|
|
import re
|
|
from typing import (
|
|
TYPE_CHECKING,
|
|
Any,
|
|
Callable,
|
|
Dict,
|
|
Iterator,
|
|
List,
|
|
Optional,
|
|
Sequence,
|
|
Set,
|
|
Tuple,
|
|
Type,
|
|
TypeVar,
|
|
Union,
|
|
)
|
|
|
|
import sphinx
|
|
from docutils import nodes
|
|
from docutils.nodes import Element, Node
|
|
from docutils.parsers.rst import Directive, directives
|
|
from docutils.parsers.rst.states import RSTState
|
|
from docutils.statemachine import StringList, ViewList
|
|
from sphinx.application import Sphinx
|
|
from sphinx.errors import ExtensionError
|
|
from sphinx.util import logging
|
|
from sphinx.util.docstrings import prepare_docstring
|
|
from sphinx.util.docutils import SphinxDirective, switch_source_input
|
|
from sphinx.util.nodes import nested_parse_with_titles
|
|
|
|
import dbusdomain
|
|
from dbusparser import parse_dbus_xml
|
|
|
|
logger = logging.getLogger(__name__)
|
|
|
|
__version__ = "1.0"
|
|
|
|
|
|
class DBusDoc:
|
|
def __init__(self, sphinx_directive, dbusfile):
|
|
self._cur_doc = None
|
|
self._sphinx_directive = sphinx_directive
|
|
self._dbusfile = dbusfile
|
|
self._top_node = nodes.section()
|
|
self.result = StringList()
|
|
self.indent = ""
|
|
|
|
def add_line(self, line: str, *lineno: int) -> None:
|
|
"""Append one line of generated reST to the output."""
|
|
if line.strip(): # not a blank line
|
|
self.result.append(self.indent + line, self._dbusfile, *lineno)
|
|
else:
|
|
self.result.append("", self._dbusfile, *lineno)
|
|
|
|
def add_method(self, method):
|
|
self.add_line(f".. dbus:method:: {method.name}")
|
|
self.add_line("")
|
|
self.indent += " "
|
|
for arg in method.in_args:
|
|
self.add_line(f":arg {arg.signature} {arg.name}: {arg.doc_string}")
|
|
for arg in method.out_args:
|
|
self.add_line(f":ret {arg.signature} {arg.name}: {arg.doc_string}")
|
|
self.add_line("")
|
|
for line in prepare_docstring("\n" + method.doc_string):
|
|
self.add_line(line)
|
|
self.indent = self.indent[:-3]
|
|
|
|
def add_signal(self, signal):
|
|
self.add_line(f".. dbus:signal:: {signal.name}")
|
|
self.add_line("")
|
|
self.indent += " "
|
|
for arg in signal.args:
|
|
self.add_line(f":arg {arg.signature} {arg.name}: {arg.doc_string}")
|
|
self.add_line("")
|
|
for line in prepare_docstring("\n" + signal.doc_string):
|
|
self.add_line(line)
|
|
self.indent = self.indent[:-3]
|
|
|
|
def add_property(self, prop):
|
|
self.add_line(f".. dbus:property:: {prop.name}")
|
|
self.indent += " "
|
|
self.add_line(f":type: {prop.signature}")
|
|
access = {"read": "readonly", "write": "writeonly", "readwrite": "readwrite"}[
|
|
prop.access
|
|
]
|
|
self.add_line(f":{access}:")
|
|
if prop.emits_changed_signal:
|
|
self.add_line(f":emits-changed: yes")
|
|
self.add_line("")
|
|
for line in prepare_docstring("\n" + prop.doc_string):
|
|
self.add_line(line)
|
|
self.indent = self.indent[:-3]
|
|
|
|
def add_interface(self, iface):
|
|
self.add_line(f".. dbus:interface:: {iface.name}")
|
|
self.add_line("")
|
|
self.indent += " "
|
|
for line in prepare_docstring("\n" + iface.doc_string):
|
|
self.add_line(line)
|
|
for method in iface.methods:
|
|
self.add_method(method)
|
|
for sig in iface.signals:
|
|
self.add_signal(sig)
|
|
for prop in iface.properties:
|
|
self.add_property(prop)
|
|
self.indent = self.indent[:-3]
|
|
|
|
|
|
def parse_generated_content(state: RSTState, content: StringList) -> List[Node]:
|
|
"""Parse a generated content by Documenter."""
|
|
with switch_source_input(state, content):
|
|
node = nodes.paragraph()
|
|
node.document = state.document
|
|
state.nested_parse(content, 0, node)
|
|
|
|
return node.children
|
|
|
|
|
|
class DBusDocDirective(SphinxDirective):
|
|
"""Extract documentation from the specified D-Bus XML file"""
|
|
|
|
has_content = True
|
|
required_arguments = 1
|
|
optional_arguments = 0
|
|
final_argument_whitespace = True
|
|
|
|
def run(self):
|
|
reporter = self.state.document.reporter
|
|
|
|
try:
|
|
source, lineno = reporter.get_source_and_line(self.lineno) # type: ignore
|
|
except AttributeError:
|
|
source, lineno = (None, None)
|
|
|
|
logger.debug("[dbusdoc] %s:%s: input:\n%s", source, lineno, self.block_text)
|
|
|
|
env = self.state.document.settings.env
|
|
dbusfile = env.config.qapidoc_srctree + "/" + self.arguments[0]
|
|
with open(dbusfile, "rb") as f:
|
|
xml_data = f.read()
|
|
xml = parse_dbus_xml(xml_data)
|
|
doc = DBusDoc(self, dbusfile)
|
|
for iface in xml:
|
|
doc.add_interface(iface)
|
|
|
|
result = parse_generated_content(self.state, doc.result)
|
|
return result
|
|
|
|
|
|
def setup(app: Sphinx) -> Dict[str, Any]:
|
|
"""Register dbus-doc directive with Sphinx"""
|
|
app.add_config_value("dbusdoc_srctree", None, "env")
|
|
app.add_directive("dbus-doc", DBusDocDirective)
|
|
dbusdomain.setup(app)
|
|
|
|
return dict(version=__version__, parallel_read_safe=True, parallel_write_safe=True)
|