From: Cleber Rosa <crosa@redhat.com>
To: John Snow <jsnow@redhat.com>
Cc: qemu-devel@nongnu.org, Eduardo Habkost <ehabkost@redhat.com>,
Markus Armbruster <armbru@redhat.com>
Subject: Re: [PATCH v3 06/47] [DO-NOT-MERGE] docs: enable sphinx-autodoc for scripts/qapi
Date: Tue, 29 Sep 2020 00:00:27 -0400 [thread overview]
Message-ID: <20200929040027.GG700868@localhost.localdomain> (raw)
In-Reply-To: <20200925002900.465855-7-jsnow@redhat.com>
[-- Attachment #1: Type: text/plain, Size: 7387 bytes --]
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.
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
next prev parent reply other threads:[~2020-09-29 4:02 UTC|newest]
Thread overview: 75+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-09-25 0:28 [PATCH v3 00/47] qapi: static typing conversion, pt1 John Snow
2020-09-25 0:28 ` [PATCH v3 01/47] [DO-NOT-MERGE] docs: replace single backtick (`) with double-backtick (``) John Snow
2020-09-29 2:47 ` Cleber Rosa
2020-09-25 0:28 ` [PATCH v3 02/47] [DO-NOT-MERGE] docs: repair broken references John Snow
2020-09-29 2:48 ` Cleber Rosa
2020-09-29 3:14 ` Cleber Rosa
2020-09-29 15:30 ` John Snow
2020-09-29 18:16 ` John Snow
2020-09-25 0:28 ` [PATCH v3 03/47] [DO-NOT-MERGE] docs/sphinx: change default role to "any" John Snow
2020-09-29 3:30 ` Cleber Rosa
2020-09-29 15:33 ` John Snow
2020-09-29 18:20 ` John Snow
2020-09-25 0:28 ` [PATCH v3 04/47] qapi: modify docstrings to be sphinx-compatible John Snow
2020-09-29 3:39 ` Cleber Rosa
2020-09-29 15:37 ` John Snow
2020-09-25 0:28 ` [PATCH v3 05/47] qapi/doc.py: Change code templates from function to string John Snow
2020-09-25 8:59 ` Markus Armbruster
2020-09-25 14:23 ` John Snow
2020-09-29 3:51 ` Cleber Rosa
2020-09-29 18:25 ` John Snow
2020-09-25 0:28 ` [PATCH v3 06/47] [DO-NOT-MERGE] docs: enable sphinx-autodoc for scripts/qapi John Snow
2020-09-29 4:00 ` Cleber Rosa [this message]
2020-09-29 18:30 ` John Snow
2020-09-25 0:28 ` [PATCH v3 07/47] qapi-gen: Separate arg-parsing from generation John Snow
2020-09-29 4:02 ` Cleber Rosa
2020-09-25 0:28 ` [PATCH v3 08/47] qapi: move generator entrypoint into module John Snow
2020-09-25 0:28 ` [PATCH v3 09/47] [DO-NOT-MERGE] docs: add scripts/qapi/main to python manual John Snow
2020-09-25 0:28 ` [PATCH v3 10/47] qapi: Prefer explicit relative imports John Snow
2020-09-25 0:28 ` [PATCH v3 11/47] qapi: Remove wildcard includes John Snow
2020-09-25 0:28 ` [PATCH v3 12/47] qapi: enforce import order/styling with isort John Snow
2020-09-25 9:20 ` Markus Armbruster
2020-09-25 15:26 ` John Snow
2020-09-28 12:13 ` Markus Armbruster
2020-09-28 14:34 ` John Snow
2020-09-29 4:13 ` Cleber Rosa
2020-09-29 4:15 ` Cleber Rosa
2020-09-25 0:28 ` [PATCH v3 13/47] qapi: delint using flake8 John Snow
2020-09-25 0:28 ` [PATCH v3 14/47] qapi: add pylintrc John Snow
2020-09-25 0:28 ` [PATCH v3 15/47] qapi/common.py: Remove python compatibility workaround John Snow
2020-09-25 0:28 ` [PATCH v3 16/47] qapi/common.py: Add indent manager John Snow
2020-09-25 0:28 ` [PATCH v3 17/47] qapi/common.py: delint with pylint John Snow
2020-09-25 0:28 ` [PATCH v3 18/47] qapi/common.py: Replace one-letter 'c' variable John Snow
2020-09-25 0:28 ` [PATCH v3 19/47] qapi/common.py: check with pylint John Snow
2020-09-25 0:28 ` [PATCH v3 20/47] qapi/common.py: add type hint annotations John Snow
2020-09-25 0:28 ` [PATCH v3 21/47] qapi/common.py: Convert comments into docstrings, and elaborate John Snow
2020-09-25 0:28 ` [PATCH v3 22/47] qapi/common.py: move build_params into gen.py John Snow
2020-09-25 0:28 ` [PATCH v3 23/47] qapi: establish mypy type-checking baseline John Snow
2020-09-29 4:17 ` Cleber Rosa
2020-09-25 0:28 ` [PATCH v3 24/47] qapi/events.py: add type hint annotations John Snow
2020-09-25 0:28 ` [PATCH v3 25/47] qapi/events.py: Move comments into docstrings John Snow
2020-09-25 0:28 ` [PATCH v3 26/47] qapi/commands.py: Don't re-bind to variable of different type John Snow
2020-09-25 0:28 ` [PATCH v3 27/47] qapi/commands.py: add type hint annotations John Snow
2020-09-25 0:28 ` [PATCH v3 28/47] qapi/commands.py: enable checking with mypy John Snow
2020-09-25 0:28 ` [PATCH v3 29/47] qapi/source.py: add type hint annotations John Snow
2020-09-29 4:18 ` Cleber Rosa
2020-09-25 0:28 ` [PATCH v3 30/47] qapi/source.py: delint with pylint John Snow
2020-09-25 0:28 ` [PATCH v3 31/47] qapi/gen.py: Fix edge-case of _is_user_module John Snow
2020-09-29 4:22 ` Cleber Rosa
2020-09-25 0:28 ` [PATCH v3 32/47] qapi/gen.py: add type hint annotations John Snow
2020-09-25 0:28 ` [PATCH v3 33/47] qapi/gen.py: Enable checking with mypy John Snow
2020-09-25 0:28 ` [PATCH v3 34/47] qapi/gen.py: Remove unused parameter John Snow
2020-09-25 0:28 ` [PATCH v3 35/47] qapi/gen.py: update write() to be more idiomatic John Snow
2020-09-25 0:28 ` [PATCH v3 36/47] qapi/gen.py: delint with pylint John Snow
2020-09-25 0:28 ` [PATCH v3 37/47] qapi/introspect.py: assert obj is a dict when features are given John Snow
2020-09-25 0:28 ` [PATCH v3 38/47] qapi/instrospect.py: add preliminary type hint annotations John Snow
2020-09-25 0:28 ` [PATCH v3 39/47] qapi/introspect.py: add _gen_features helper John Snow
2020-09-25 0:28 ` [PATCH v3 40/47] qapi/introspect.py: Unify return type of _make_tree() John Snow
2020-09-25 0:28 ` [PATCH v3 41/47] qapi/introspect.py: replace 'extra' dict with 'comment' argument John Snow
2020-09-25 0:28 ` [PATCH v3 42/47] qapi/introspect.py: create a typed 'Node' data structure John Snow
2020-09-25 0:28 ` [PATCH v3 43/47] qapi/types.py: add type hint annotations John Snow
2020-09-25 0:28 ` [PATCH v3 44/47] qapi/types.py: remove one-letter variables John Snow
2020-09-25 0:28 ` [PATCH v3 45/47] qapi/visit.py: assert tag_member contains a QAPISchemaEnumType John Snow
2020-09-25 0:28 ` [PATCH v3 46/47] qapi/visit.py: remove unused parameters from gen_visit_object John Snow
2020-09-25 0:29 ` [PATCH v3 47/47] qapi/visit.py: add type hint annotations John Snow
2020-09-28 15:17 ` [PATCH v3 00/47] qapi: static typing conversion, pt1 John Snow
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200929040027.GG700868@localhost.localdomain \
--to=crosa@redhat.com \
--cc=armbru@redhat.com \
--cc=ehabkost@redhat.com \
--cc=jsnow@redhat.com \
--cc=qemu-devel@nongnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).