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

[Cleber Rosa]

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"?

>  
>  # -- 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?

- Cleber.

signature.asc
Description: PGP signature