[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH 14/37] qapi/common.py: Move comments into docstrings
From: |
Eduardo Habkost |
Subject: |
Re: [PATCH 14/37] qapi/common.py: Move comments into docstrings |
Date: |
Thu, 17 Sep 2020 15:14:55 -0400 |
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.
Signed-off-by: Eduardo Habkost <ehabkost@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::
--
2.26.2
--
Eduardo
- Re: [PATCH 10/37] qapi/common.py: delint with pylint, (continued)
[PATCH 12/37] qapi/common.py: check with pylint, John Snow, 2020/09/15
[PATCH 11/37] qapi/common.py: Replace one-letter 'c' variable, John Snow, 2020/09/15
[PATCH 14/37] qapi/common.py: Move comments into docstrings, John Snow, 2020/09/15
- Re: [PATCH 14/37] qapi/common.py: Move comments into docstrings, Markus Armbruster, 2020/09/17
- Re: [PATCH 14/37] qapi/common.py: Move comments into docstrings, John Snow, 2020/09/17
- Re: [PATCH 14/37] qapi/common.py: Move comments into docstrings,
Eduardo Habkost <=
- Re: [PATCH 14/37] qapi/common.py: Move comments into docstrings, John Snow, 2020/09/17
- Re: [PATCH 14/37] qapi/common.py: Move comments into docstrings, Markus Armbruster, 2020/09/24
- Re: [PATCH 14/37] qapi/common.py: Move comments into docstrings, John Snow, 2020/09/24
- Re: [PATCH 14/37] qapi/common.py: Move comments into docstrings, Markus Armbruster, 2020/09/25
- Re: [PATCH 14/37] qapi/common.py: Move comments into docstrings, John Snow, 2020/09/25
[PATCH 13/37] qapi/common.py: add notational type hints, John Snow, 2020/09/15