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 <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:: -- 2.26.2 -- Eduardo