[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH v2 04/21] docs/qapidoc: delint a tiny portion of the module
From: |
John Snow |
Subject: |
[PATCH v2 04/21] docs/qapidoc: delint a tiny portion of the module |
Date: |
Wed, 26 Jun 2024 18:21:10 -0400 |
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 <jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
---
docs/sphinx/qapidoc.py | 62 +++++++++++++++++++++++++-----------------
1 file changed, 37 insertions(+), 25 deletions(-)
diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index 3c0565d0ceb..659e507353a 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -28,26 +28,33 @@
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 @@ def get_document_nodes(self):
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 @@ def do_parse(self, rstlist, node):
# 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 @@ def do_parse(self, rstlist, node):
def setup(app):
- """ Register qapi-doc directive with Sphinx"""
- app.add_config_value('qapidoc_srctree', None, 'env')
- app.add_directive('qapi-doc', QAPIDocDirective)
+ """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
- )
+ return {
+ "version": __version__,
+ "parallel_read_safe": True,
+ "parallel_write_safe": True,
+ }
--
2.45.0
- [PATCH v2 00/21] qapi: convert "Note" and "Example" sections to rST, John Snow, 2024/06/26
- [PATCH v2 01/21] [DO-NOT-MERGE]: Add some ad-hoc linting helpers., John Snow, 2024/06/26
- [PATCH v2 02/21] qapi: linter fixups, John Snow, 2024/06/26
- [PATCH v2 03/21] docs/qapidoc: remove unused intersperse function, John Snow, 2024/06/26
- [PATCH v2 04/21] docs/qapidoc: delint a tiny portion of the module,
John Snow <=
- [PATCH v2 05/21] qapi/parser: preserve indentation in QAPIDoc sections, John Snow, 2024/06/26
- [PATCH v2 06/21] qapi/parser: fix comment parsing immediately following a doc block, John Snow, 2024/06/26
- [PATCH v2 07/21] docs/qapidoc: fix nested parsing under untagged sections, John Snow, 2024/06/26