Re: [PATCH v3 06/47] [DO-NOT-MERGE] docs: enable sphinx-autodoc for scripts/qapi

[John Snow]

On 9/29/20 12:00 AM, Cleber Rosa wrote:
> On Thu, Sep 24, 2020 at 08:28:19PM -0400, John Snow wrote:
> > Signed-off-by: John Snow <jsnow@redhat.com>
> > ---
> >   docs/conf.py                          |  6 +++++-
> >   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.doc.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.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, 131 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.doc.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.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 a68f616d5a..d03ef465a6 100644
> > --- a/docs/conf.py
> > +++ b/docs/conf.py
> > @@ -54,6 +54,9 @@
> >   #
> >   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"))
> > +
>
> Do I hear qapi asking to moved out of "scripts" and becoming more like
> "python/qemu"?

Once all six parts of this series goes in I will move it to the python 
folder, but you're about 150 patches early.

> >   
> >   # -- General configuration ------------------------------------------------
> >   
> > @@ -67,7 +70,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']
> > +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..04726ca787 100644
> > --- a/docs/devel/index.rst
> > +++ b/docs/devel/index.rst
> > @@ -31,3 +31,4 @@ Contents:
> >      reset
> >      s390-dasd-ipl
> >      clocks
> > +   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.doc.rst b/docs/devel/python/qapi.doc.rst
> > new file mode 100644
> > index 0000000000..556c2bca1f
> > --- /dev/null
> > +++ b/docs/devel/python/qapi.doc.rst
> > @@ -0,0 +1,7 @@
> > +qapi.doc module
> > +===============
> > +
> > +.. automodule:: qapi.doc
> > +   :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.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..24fbf34981
> > --- /dev/null
> > +++ b/docs/devel/python/qapi.rst
> > @@ -0,0 +1,26 @@
> > +qapi package
> > +============
> > +
> > +.. automodule:: qapi
> > +   :members:
> > +   :undoc-members:
> > +   :show-inheritance:
> > +
>
> This renders *very* timidly, ending up almost invisible.  Also,
> there's no useful introduction to what this "qapi" when you enter this
> section.
>
> Maybe create a "API reference" section, explaining it first?

Respectfully, "DO NOT MERGE" is written in large capital letters in the 
subject of this patch.

You are free to try to format the manual as you please at a later date, 
but it's not something that I will be doing right now. The purpose of 
this patch is solely to prove that my docstring formatting adheres to 
some kind of standard, and the method to prove it is nontrivial, hence 
these patches.

--js