Re: [PATCH 14/37] qapi/common.py: Move comments into docstrings

[John Snow]

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