* [PATCH v3 1/2] [DO-NOT-MERGE] docs: enable sphinx-autodoc for scripts/qapi
2022-02-04 22:42 [PATCH v3 0/2] [DO-NOT-MERGE] qapi: static typing conversion, "pt0" John Snow
@ 2022-02-04 22:42 ` John Snow
2022-02-04 22:42 ` [PATCH v3 2/2] [DO-NOT-MERGE]: Add some ad-hoc linting helpers John Snow
1 sibling, 0 replies; 3+ messages in thread
From: John Snow @ 2022-02-04 22:42 UTC (permalink / raw)
To: qemu-devel; +Cc: Marc-André Lureau, John Snow, Markus Armbruster
This is just 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 49dab44cca..9ab250d87a 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -71,7 +71,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 afd937535e..245463d4f8 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -48,3 +48,4 @@ modifying QEMU's source code.
trivial-patches
submitting-a-patch
submitting-a-pull-request
+ 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.34.1
^ permalink raw reply related [flat|nested] 3+ messages in thread* [PATCH v3 2/2] [DO-NOT-MERGE]: Add some ad-hoc linting helpers.
2022-02-04 22:42 [PATCH v3 0/2] [DO-NOT-MERGE] qapi: static typing conversion, "pt0" John Snow
2022-02-04 22:42 ` [PATCH v3 1/2] [DO-NOT-MERGE] docs: enable sphinx-autodoc for scripts/qapi John Snow
@ 2022-02-04 22:42 ` John Snow
1 sibling, 0 replies; 3+ messages in thread
From: John Snow @ 2022-02-04 22:42 UTC (permalink / raw)
To: qemu-devel; +Cc: Marc-André Lureau, John Snow, Markus Armbruster
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.
I *think*, but can't exhaustively guarantee, that these should
work:
Python >= 3.6
isort >= 5.7.0 (But possibly earlier)
mypy >= 0.770 (Currently using 0.800)
pylint >= 2.6.0 (Currently using 2.7.4)
My python packaging series does a more exhaustive treatment and
exploration of minimum package requirements; eventually these two series
will converge and these dependencies will be handled in one place.
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..2c2f2808ca
--- /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 ../bin/git
+make -j9
+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.34.1
^ permalink raw reply related [flat|nested] 3+ messages in thread