* [PATCH v5 1/3] [DO-NOT-MERGE] docs: enable sphinx-autodoc for scripts/qapi
2023-10-04 23:05 [PATCH v5 0/3] [DO-NOT-MERGE] qapi: static typing conversion, "pt0" John Snow
@ 2023-10-04 23:05 ` John Snow
2023-10-04 23:05 ` [PATCH v5 2/3] [DO-NOT-MERGE]: Add some ad-hoc linting helpers John Snow
2023-10-04 23:05 ` [PATCH v5 3/3] qapi: re-establish linting baseline John Snow
2 siblings, 0 replies; 7+ messages in thread
From: John Snow @ 2023-10-04 23:05 UTC (permalink / raw)
To: qemu-devel
Cc: Markus Armbruster, Victor Toso de Carvalho, Peter Maydell,
Michael Roth, John Snow
This is just a POC to prove that the docstrings, where they are written,
are correct to some minimum standard. It is included here for
reviewing/testing convenience.
Signed-off-by: John Snow <jsnow@redhat.com>
---
docs/conf.py | 3 ++-
docs/devel/index.rst | 1 +
docs/devel/python/index.rst | 7 +++++++
docs/devel/python/qapi.commands.rst | 7 +++++++
docs/devel/python/qapi.common.rst | 7 +++++++
docs/devel/python/qapi.error.rst | 7 +++++++
docs/devel/python/qapi.events.rst | 7 +++++++
docs/devel/python/qapi.expr.rst | 7 +++++++
docs/devel/python/qapi.gen.rst | 7 +++++++
docs/devel/python/qapi.introspect.rst | 7 +++++++
docs/devel/python/qapi.main.rst | 7 +++++++
docs/devel/python/qapi.parser.rst | 8 ++++++++
docs/devel/python/qapi.rst | 26 ++++++++++++++++++++++++++
docs/devel/python/qapi.schema.rst | 7 +++++++
docs/devel/python/qapi.source.rst | 7 +++++++
docs/devel/python/qapi.types.rst | 7 +++++++
docs/devel/python/qapi.visit.rst | 7 +++++++
17 files changed, 128 insertions(+), 1 deletion(-)
create mode 100644 docs/devel/python/index.rst
create mode 100644 docs/devel/python/qapi.commands.rst
create mode 100644 docs/devel/python/qapi.common.rst
create mode 100644 docs/devel/python/qapi.error.rst
create mode 100644 docs/devel/python/qapi.events.rst
create mode 100644 docs/devel/python/qapi.expr.rst
create mode 100644 docs/devel/python/qapi.gen.rst
create mode 100644 docs/devel/python/qapi.introspect.rst
create mode 100644 docs/devel/python/qapi.main.rst
create mode 100644 docs/devel/python/qapi.parser.rst
create mode 100644 docs/devel/python/qapi.rst
create mode 100644 docs/devel/python/qapi.schema.rst
create mode 100644 docs/devel/python/qapi.source.rst
create mode 100644 docs/devel/python/qapi.types.rst
create mode 100644 docs/devel/python/qapi.visit.rst
diff --git a/docs/conf.py b/docs/conf.py
index e84a95e71c..4557dbe3e2 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -62,7 +62,8 @@
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
-extensions = ['kerneldoc', 'qmp_lexer', 'hxtool', 'depfile', 'qapidoc']
+extensions = ['kerneldoc', 'qmp_lexer', 'hxtool',
+ 'depfile', 'qapidoc', 'sphinx.ext.autodoc']
if sphinx.version_info[:3] > (4, 0, 0):
tags.add('sphinx4')
diff --git a/docs/devel/index.rst b/docs/devel/index.rst
index abf60457c2..eff5760177 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -34,3 +34,4 @@ the :ref:`tcg_internals`.
index-api
index-internals
index-tcg
+ python/index
diff --git a/docs/devel/python/index.rst b/docs/devel/python/index.rst
new file mode 100644
index 0000000000..31c470154b
--- /dev/null
+++ b/docs/devel/python/index.rst
@@ -0,0 +1,7 @@
+qapi
+====
+
+.. toctree::
+ :maxdepth: 4
+
+ qapi
diff --git a/docs/devel/python/qapi.commands.rst b/docs/devel/python/qapi.commands.rst
new file mode 100644
index 0000000000..018f7b08a9
--- /dev/null
+++ b/docs/devel/python/qapi.commands.rst
@@ -0,0 +1,7 @@
+qapi.commands module
+====================
+
+.. automodule:: qapi.commands
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/devel/python/qapi.common.rst b/docs/devel/python/qapi.common.rst
new file mode 100644
index 0000000000..128a90d74b
--- /dev/null
+++ b/docs/devel/python/qapi.common.rst
@@ -0,0 +1,7 @@
+qapi.common module
+==================
+
+.. automodule:: qapi.common
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/devel/python/qapi.error.rst b/docs/devel/python/qapi.error.rst
new file mode 100644
index 0000000000..980e32b63d
--- /dev/null
+++ b/docs/devel/python/qapi.error.rst
@@ -0,0 +1,7 @@
+qapi.error module
+=================
+
+.. automodule:: qapi.error
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/devel/python/qapi.events.rst b/docs/devel/python/qapi.events.rst
new file mode 100644
index 0000000000..1fce85b044
--- /dev/null
+++ b/docs/devel/python/qapi.events.rst
@@ -0,0 +1,7 @@
+qapi.events module
+==================
+
+.. automodule:: qapi.events
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/devel/python/qapi.expr.rst b/docs/devel/python/qapi.expr.rst
new file mode 100644
index 0000000000..0660270629
--- /dev/null
+++ b/docs/devel/python/qapi.expr.rst
@@ -0,0 +1,7 @@
+qapi.expr module
+================
+
+.. automodule:: qapi.expr
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/devel/python/qapi.gen.rst b/docs/devel/python/qapi.gen.rst
new file mode 100644
index 0000000000..7b495fd4bf
--- /dev/null
+++ b/docs/devel/python/qapi.gen.rst
@@ -0,0 +1,7 @@
+qapi.gen module
+===============
+
+.. automodule:: qapi.gen
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/devel/python/qapi.introspect.rst b/docs/devel/python/qapi.introspect.rst
new file mode 100644
index 0000000000..f65ebfccd1
--- /dev/null
+++ b/docs/devel/python/qapi.introspect.rst
@@ -0,0 +1,7 @@
+qapi.introspect module
+======================
+
+.. automodule:: qapi.introspect
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/devel/python/qapi.main.rst b/docs/devel/python/qapi.main.rst
new file mode 100644
index 0000000000..1255fcda63
--- /dev/null
+++ b/docs/devel/python/qapi.main.rst
@@ -0,0 +1,7 @@
+qapi.main module
+================
+
+.. automodule:: qapi.main
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/devel/python/qapi.parser.rst b/docs/devel/python/qapi.parser.rst
new file mode 100644
index 0000000000..1a8f7b347e
--- /dev/null
+++ b/docs/devel/python/qapi.parser.rst
@@ -0,0 +1,8 @@
+qapi.parser module
+==================
+
+.. automodule:: qapi.parser
+ :members:
+ :undoc-members:
+ :show-inheritance:
+ :private-members:
diff --git a/docs/devel/python/qapi.rst b/docs/devel/python/qapi.rst
new file mode 100644
index 0000000000..c762019aad
--- /dev/null
+++ b/docs/devel/python/qapi.rst
@@ -0,0 +1,26 @@
+qapi package
+============
+
+.. automodule:: qapi
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+Submodules
+----------
+
+.. toctree::
+
+ qapi.commands
+ qapi.common
+ qapi.error
+ qapi.events
+ qapi.expr
+ qapi.gen
+ qapi.introspect
+ qapi.main
+ qapi.parser
+ qapi.schema
+ qapi.source
+ qapi.types
+ qapi.visit
diff --git a/docs/devel/python/qapi.schema.rst b/docs/devel/python/qapi.schema.rst
new file mode 100644
index 0000000000..a08f75ed72
--- /dev/null
+++ b/docs/devel/python/qapi.schema.rst
@@ -0,0 +1,7 @@
+qapi.schema module
+==================
+
+.. automodule:: qapi.schema
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/devel/python/qapi.source.rst b/docs/devel/python/qapi.source.rst
new file mode 100644
index 0000000000..e61e9f6021
--- /dev/null
+++ b/docs/devel/python/qapi.source.rst
@@ -0,0 +1,7 @@
+qapi.source module
+==================
+
+.. automodule:: qapi.source
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/devel/python/qapi.types.rst b/docs/devel/python/qapi.types.rst
new file mode 100644
index 0000000000..6eea827557
--- /dev/null
+++ b/docs/devel/python/qapi.types.rst
@@ -0,0 +1,7 @@
+qapi.types module
+=================
+
+.. automodule:: qapi.types
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/devel/python/qapi.visit.rst b/docs/devel/python/qapi.visit.rst
new file mode 100644
index 0000000000..84307cbc23
--- /dev/null
+++ b/docs/devel/python/qapi.visit.rst
@@ -0,0 +1,7 @@
+qapi.visit module
+=================
+
+.. automodule:: qapi.visit
+ :members:
+ :undoc-members:
+ :show-inheritance:
--
2.41.0
^ permalink raw reply related [flat|nested] 7+ messages in thread* [PATCH v5 2/3] [DO-NOT-MERGE]: Add some ad-hoc linting helpers.
2023-10-04 23:05 [PATCH v5 0/3] [DO-NOT-MERGE] qapi: static typing conversion, "pt0" John Snow
2023-10-04 23:05 ` [PATCH v5 1/3] [DO-NOT-MERGE] docs: enable sphinx-autodoc for scripts/qapi John Snow
@ 2023-10-04 23:05 ` John Snow
2023-10-04 23:05 ` [PATCH v5 3/3] qapi: re-establish linting baseline John Snow
2 siblings, 0 replies; 7+ messages in thread
From: John Snow @ 2023-10-04 23:05 UTC (permalink / raw)
To: qemu-devel
Cc: Markus Armbruster, Victor Toso de Carvalho, Peter Maydell,
Michael Roth, John Snow
These aren't ready for upstream inclusion, because they do not properly
manage version dependencies, execution environment and so on. These are
just the tools I use in my Own Special Environment :tm: for testing and
debugging.
They've been tested only on Fedora 38 for right now, which means:
Python 3.11.4-1.fc38
pylint 2.17.4-2.fc38
mypy 1.4.0-1.fc38
isort 5.12.0-1.fc38
flake8 5.0.3-2.fc38
The python packaging work does a more exhaustive treatment and
exploration of minimum (and maximum) package requirements; the hope is
that eventually these two series will converge and these dependencies
will all be handled by configuration in qemu.git/python/.
For now, this is just a baseline under one environment to give us some
guidance.
Signed-off-by: John Snow <jsnow@redhat.com>
---
scripts/qapi-lint.sh | 29 +++++++++++++++++++++++++++++
scripts/qapi/Makefile | 5 +++++
2 files changed, 34 insertions(+)
create mode 100755 scripts/qapi-lint.sh
create mode 100644 scripts/qapi/Makefile
diff --git a/scripts/qapi-lint.sh b/scripts/qapi-lint.sh
new file mode 100755
index 0000000000..6072f389a2
--- /dev/null
+++ b/scripts/qapi-lint.sh
@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+set -e
+
+if [[ -f qapi/.flake8 ]]; then
+ echo "flake8 --config=qapi/.flake8 qapi/"
+ flake8 --config=qapi/.flake8 qapi/
+fi
+if [[ -f qapi/pylintrc ]]; then
+ echo "pylint --rcfile=qapi/pylintrc qapi/"
+ pylint --rcfile=qapi/pylintrc qapi/
+fi
+if [[ -f qapi/mypy.ini ]]; then
+ echo "mypy --config-file=qapi/mypy.ini qapi/"
+ mypy --config-file=qapi/mypy.ini qapi/
+fi
+
+if [[ -f qapi/.isort.cfg ]]; then
+ pushd qapi
+ echo "isort -c ."
+ isort -c .
+ popd
+fi
+
+pushd ../build
+make -j13
+make check-qapi-schema
+make docs
+make sphinxdocs
+popd
diff --git a/scripts/qapi/Makefile b/scripts/qapi/Makefile
new file mode 100644
index 0000000000..314e8a5505
--- /dev/null
+++ b/scripts/qapi/Makefile
@@ -0,0 +1,5 @@
+check:
+ isort -c .
+ flake8 .
+ cd .. && pylint --rcfile=qapi/pylintrc qapi
+ cd .. && mypy -p qapi --config-file=qapi/mypy.ini
--
2.41.0
^ permalink raw reply related [flat|nested] 7+ messages in thread
* [PATCH v5 3/3] qapi: re-establish linting baseline
2023-10-04 23:05 [PATCH v5 0/3] [DO-NOT-MERGE] qapi: static typing conversion, "pt0" John Snow
2023-10-04 23:05 ` [PATCH v5 1/3] [DO-NOT-MERGE] docs: enable sphinx-autodoc for scripts/qapi John Snow
2023-10-04 23:05 ` [PATCH v5 2/3] [DO-NOT-MERGE]: Add some ad-hoc linting helpers John Snow
@ 2023-10-04 23:05 ` John Snow
2023-10-05 6:44 ` Philippe Mathieu-Daudé
2023-10-18 8:53 ` Markus Armbruster
2 siblings, 2 replies; 7+ messages in thread
From: John Snow @ 2023-10-04 23:05 UTC (permalink / raw)
To: qemu-devel
Cc: Markus Armbruster, Victor Toso de Carvalho, Peter Maydell,
Michael Roth, John Snow
Some very minor housekeeping to make the linters happy once more.
Signed-off-by: John Snow <jsnow@redhat.com>
---
scripts/qapi/gen.py | 2 +-
scripts/qapi/parser.py | 5 +++--
2 files changed, 4 insertions(+), 3 deletions(-)
diff --git a/scripts/qapi/gen.py b/scripts/qapi/gen.py
index bf5716b5f3..5412716617 100644
--- a/scripts/qapi/gen.py
+++ b/scripts/qapi/gen.py
@@ -13,8 +13,8 @@
from contextlib import contextmanager
import os
-import sys
import re
+import sys
from typing import (
Dict,
Iterator,
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index 22e7bcc4b1..bf31018aef 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -22,6 +22,7 @@
Dict,
List,
Mapping,
+ Match,
Optional,
Set,
Union,
@@ -563,11 +564,11 @@ def end_comment(self) -> None:
self._switch_section(QAPIDoc.NullSection(self._parser))
@staticmethod
- def _match_at_name_colon(string: str):
+ def _match_at_name_colon(string: str) -> Optional[Match[str]]:
return re.match(r'@([^:]*): *', string)
@staticmethod
- def _match_section_tag(string: str):
+ def _match_section_tag(string: str) -> Optional[Match[str]]:
return re.match(r'(Returns|Since|Notes?|Examples?|TODO): *', string)
def _append_body_line(self, line: str) -> None:
--
2.41.0
^ permalink raw reply related [flat|nested] 7+ messages in thread