On 9/17/20 3:14 PM, Eduardo Habkost wrote:
On Thu, Sep 17, 2020 at 02:44:53PM -0400, John Snow wrote:
[...]
Having said this, I have not found any tool to date that actually *checks*
these comments for consistency. The pycharm IDE interactively highlights
them when it senses that you have made a mistake, but that cannot be worked
into our CI process that I know of - it's a proprietary checker.
So right now, they're just plaintext that I am writing to approximate the
Sphinx style until such time as I enable autodoc for the module and
fine-tune the actual formatting and so on.
After applying this series, I only had to make two small tweaks
to make Sphinx + autodoc happy with the docstrings you wrote.
With the following patch, "make sphinxdocs" will generate the
QAPI Python module documentation at docs/devel/qapi.html.
I had to explicitly skip qapi/doc.py because autodoc thinks the
string constants are documentation strings.
Awesome!
I think I am going to delay explicitly pursuing writing a manual for the
QAPI parser for now, but it's good to know I am not too far off. I'm
going to target the mypy conversions first, because they can be invasive
and full of churn.
When I get there, though ... I am thinking I should add this as
Devel/QAPI Parser.
Signed-off-by: Eduardo Habkost <ehabk...@redhat.com>
---
docs/conf.py | 5 +++-
docs/devel/index.rst | 1 +
docs/devel/qapi.rst | 67 ++++++++++++++++++++++++++++++++++++++++++
scripts/qapi/common.py | 2 +-
scripts/qapi/gen.py | 2 +-
5 files changed, 74 insertions(+), 3 deletions(-)
create mode 100644 docs/devel/qapi.rst
diff --git a/docs/conf.py b/docs/conf.py
index 8aeac40124..85be0e1860 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -54,6 +54,9 @@ except NameError:
#
sys.path.insert(0, os.path.join(qemu_docdir, "sphinx"))
+# Make scripts/qapi module available for autodoc
+sys.path.insert(0, os.path.join(qemu_docdir, "../scripts"))
+
# -- General configuration ------------------------------------------------
@@ -67,7 +70,7 @@ needs_sphinx = '1.6'
# 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']
+extensions = ['kerneldoc', 'qmp_lexer', 'hxtool', 'depfile',
'sphinx.ext.autodoc']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
diff --git a/docs/devel/index.rst b/docs/devel/index.rst
index 04773ce076..a4d2cb9893 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -31,3 +31,4 @@ Contents:
reset
s390-dasd-ipl
clocks
+ qapi
diff --git a/docs/devel/qapi.rst b/docs/devel/qapi.rst
new file mode 100644
index 0000000000..9130ef84c6
--- /dev/null
+++ b/docs/devel/qapi.rst
@@ -0,0 +1,67 @@
+QAPI Python module reference
+============================
+
+.. automodule:: qapi
+ :members:
+ :undoc-members:
+
+.. automodule:: qapi.commands
+ :members:
+ :undoc-members:
+
+.. automodule:: qapi.common
+ :members:
+ :undoc-members:
+
+.. automodule:: qapi.debug
+ :members:
+ :undoc-members:
+
+.. automodule:: qapi.error
+ :members:
+ :undoc-members:
+
+.. automodule:: qapi.events
+ :members:
+ :undoc-members:
+
+.. automodule:: qapi.expr
+ :members:
+ :undoc-members:
+
+.. automodule:: qapi.gen
+ :members:
+ :undoc-members:
+
+.. automodule:: qapi.introspect
+ :members:
+ :undoc-members:
+
+.. automodule:: qapi.params
+ :members:
+ :undoc-members:
+
+.. automodule:: qapi.parser
+ :members:
+ :undoc-members:
+
+.. automodule:: qapi.schema
+ :members:
+ :undoc-members:
+
+.. automodule:: qapi.script
+ :members:
+ :undoc-members:
+
+.. automodule:: qapi.source
+ :members:
+ :undoc-members:
+
+.. automodule:: qapi.types
+ :members:
+ :undoc-members:
+
+.. automodule:: qapi.visit
+ :members:
+ :undoc-members:
+
diff --git a/scripts/qapi/common.py b/scripts/qapi/common.py
index 0b1af694e6..7c8c4cb846 100644
--- a/scripts/qapi/common.py
+++ b/scripts/qapi/common.py
@@ -78,7 +78,7 @@ def c_name(name: str, protect: bool = True) -> str:
:param name: The name to map.
:param protect: If true, avoid returning certain ticklish identifiers
- (like C keywords) by prepending 'q_'.
+ (like C keywords) by prepending ``q_``.
"""
# ANSI X3J11/88-090, 3.1.1
c89_words = set(['auto', 'break', 'case', 'char', 'const', 'continue',
diff --git a/scripts/qapi/gen.py b/scripts/qapi/gen.py
index 0a72aecdd0..cf33732256 100644
--- a/scripts/qapi/gen.py
+++ b/scripts/qapi/gen.py
@@ -161,7 +161,7 @@ def ifcontext(ifcond: List[str],
*args: QAPIGenCCode) -> Generator[None, None, None]:
"""A 'with' statement context manager to wrap with start_if()/end_if()
- *args: any number of QAPIGenCCode
+ :param args: any number of QAPIGenCCode
Example::