From 36c6dcc26693ac385cd3c130a4804898b2d7d388 Mon Sep 17 00:00:00 2001 From: John Snow Date: Wed, 26 Jun 2024 18:21:10 -0400 Subject: docs/qapidoc: delint a tiny portion of the module In a forthcoming series that adds a new QMP documentation generator, it will be helpful to have a linting baseline. However, there's no need to shuffle around the deck chairs too much, because most of this code will be removed once that new qapidoc generator (the "transmogrifier") is in place. To ease my pain: just turn off the black auto-formatter for most, but not all, of qapidoc.py. This will help ensure that *new* code follows a coding standard without bothering too much with cleaning up the existing code. Code that I intend to keep is still subject to the delinting beam. Signed-off-by: John Snow Reviewed-by: Markus Armbruster Message-ID: <20240626222128.406106-5-jsnow@redhat.com> Signed-off-by: Markus Armbruster --- docs/sphinx/qapidoc.py | 64 ++++++++++++++++++++++++++++++-------------------- 1 file changed, 38 insertions(+), 26 deletions(-) (limited to 'docs/sphinx/qapidoc.py') diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 3c0565d..659e507 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -28,26 +28,33 @@ import os import re from docutils import nodes +from docutils.parsers.rst import Directive, directives from docutils.statemachine import ViewList -from docutils.parsers.rst import directives, Directive -from sphinx.errors import ExtensionError -from sphinx.util.nodes import nested_parse_with_titles -import sphinx -from qapi.gen import QAPISchemaVisitor from qapi.error import QAPIError, QAPISemError +from qapi.gen import QAPISchemaVisitor from qapi.schema import QAPISchema +import sphinx +from sphinx.errors import ExtensionError +from sphinx.util.nodes import nested_parse_with_titles + # Sphinx up to 1.6 uses AutodocReporter; 1.7 and later # use switch_source_input. Check borrowed from kerneldoc.py. -Use_SSI = sphinx.__version__[:3] >= '1.7' -if Use_SSI: +USE_SSI = sphinx.__version__[:3] >= "1.7" +if USE_SSI: from sphinx.util.docutils import switch_source_input else: - from sphinx.ext.autodoc import AutodocReporter + from sphinx.ext.autodoc import ( # pylint: disable=no-name-in-module + AutodocReporter, + ) -__version__ = '1.0' +__version__ = "1.0" + + +# Disable black auto-formatter until re-enabled: +# fmt: off class QAPISchemaGenRSTVisitor(QAPISchemaVisitor): @@ -441,6 +448,10 @@ class QAPISchemaGenRSTVisitor(QAPISchemaVisitor): return self._top_node.children +# Turn the black formatter on for the rest of the file. +# fmt: on + + class QAPISchemaGenDepVisitor(QAPISchemaVisitor): """A QAPI schema visitor which adds Sphinx dependencies each module @@ -448,34 +459,34 @@ class QAPISchemaGenDepVisitor(QAPISchemaVisitor): that the generated documentation output depends on the input schema file associated with each module in the QAPI input. """ + def __init__(self, env, qapidir): self._env = env self._qapidir = qapidir def visit_module(self, name): if name != "./builtin": - qapifile = self._qapidir + '/' + name + qapifile = self._qapidir + "/" + name self._env.note_dependency(os.path.abspath(qapifile)) super().visit_module(name) class QAPIDocDirective(Directive): """Extract documentation from the specified QAPI .json file""" + required_argument = 1 optional_arguments = 1 - option_spec = { - 'qapifile': directives.unchanged_required - } + option_spec = {"qapifile": directives.unchanged_required} has_content = False def new_serialno(self): """Return a unique new ID string suitable for use as a node's ID""" env = self.state.document.settings.env - return 'qapidoc-%d' % env.new_serialno('qapidoc') + return "qapidoc-%d" % env.new_serialno("qapidoc") def run(self): env = self.state.document.settings.env - qapifile = env.config.qapidoc_srctree + '/' + self.arguments[0] + qapifile = env.config.qapidoc_srctree + "/" + self.arguments[0] qapidir = os.path.dirname(qapifile) try: @@ -513,13 +524,14 @@ class QAPIDocDirective(Directive): # plain self.state.nested_parse(), and so we can drop the saving # of title_styles and section_level that kerneldoc.py does, # because nested_parse_with_titles() does that for us. - if Use_SSI: + if USE_SSI: with switch_source_input(self.state, rstlist): nested_parse_with_titles(self.state, rstlist, node) else: save = self.state.memo.reporter self.state.memo.reporter = AutodocReporter( - rstlist, self.state.memo.reporter) + rstlist, self.state.memo.reporter + ) try: nested_parse_with_titles(self.state, rstlist, node) finally: @@ -527,12 +539,12 @@ class QAPIDocDirective(Directive): def setup(app): - """ Register qapi-doc directive with Sphinx""" - app.add_config_value('qapidoc_srctree', None, 'env') - app.add_directive('qapi-doc', QAPIDocDirective) - - return dict( - version=__version__, - parallel_read_safe=True, - parallel_write_safe=True - ) + """Register qapi-doc directive with Sphinx""" + app.add_config_value("qapidoc_srctree", None, "env") + app.add_directive("qapi-doc", QAPIDocDirective) + + return { + "version": __version__, + "parallel_read_safe": True, + "parallel_write_safe": True, + } -- cgit v1.1