From: Markus Armbruster <armbru@redhat.com>
To: John Snow <jsnow@redhat.com>
Cc: "Peter Maydell" <peter.maydell@linaro.org>,
"Thomas Huth" <thuth@redhat.com>,
"Eduardo Habkost" <ehabkost@redhat.com>,
qemu-devel@nongnu.org, "Cleber Rosa" <crosa@redhat.com>,
"Alex Bennée" <alex.bennee@linaro.org>
Subject: Re: [PATCH v4 04/46] qapi: modify docstrings to be sphinx-compatible
Date: Wed, 30 Sep 2020 10:47:17 +0200 [thread overview]
Message-ID: <87wo0bejmy.fsf@dusky.pond.sub.org> (raw)
In-Reply-To: <20200930043150.1454766-5-jsnow@redhat.com> (John Snow's message of "Wed, 30 Sep 2020 00:31:08 -0400")
John Snow <jsnow@redhat.com> writes:
> I did not say "sphinx beautiful", just "sphinx compatible". They will
> not throw errors when parsed and interpreted as ReST.
"Bang on the keyboard until Sphinx doesn't throw errors anymore" might
be good enough for a certain kind of mathematician, but a constructive
solution needs a bit more direction. Is there a specification to
follow? Other useful resources?
>
> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
> scripts/qapi/gen.py | 6 ++++--
> scripts/qapi/parser.py | 9 +++++----
> 2 files changed, 9 insertions(+), 6 deletions(-)
>
> diff --git a/scripts/qapi/gen.py b/scripts/qapi/gen.py
> index ca66c82b5b8..fc19b2aeb9b 100644
> --- a/scripts/qapi/gen.py
> +++ b/scripts/qapi/gen.py
> @@ -154,9 +154,11 @@ def _bottom(self):
>
> @contextmanager
> def ifcontext(ifcond, *args):
> - """A 'with' statement context manager to wrap with start_if()/end_if()
> + """
> + A 'with' statement context manager that wraps with `start_if` and `end_if`.
Sadly, the fact that start_if() and end_if() are functions isn't
immediately obvious anymore.
I've seen :func:`start_if` elsewhere. Is this something we should or
want to use?
>
> - *args: any number of QAPIGenCCode
> + :param ifcond: List of conditionals
> + :param args: any number of `QAPIGenCCode`.
>
> Example::
>
> diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
> index 9d1a3e2eea9..02983979965 100644
> --- a/scripts/qapi/parser.py
> +++ b/scripts/qapi/parser.py
> @@ -381,10 +381,11 @@ def append(self, line):
>
> The way that the line is dealt with depends on which part of
> the documentation we're parsing right now:
> - * The body section: ._append_line is ._append_body_line
> - * An argument section: ._append_line is ._append_args_line
> - * A features section: ._append_line is ._append_features_line
> - * An additional section: ._append_line is ._append_various_line
> +
> + * The body section: ._append_line is ._append_body_line
> + * An argument section: ._append_line is ._append_args_line
> + * A features section: ._append_line is ._append_features_line
> + * An additional section: ._append_line is ._append_various_line
> """
> line = line[1:]
> if not line:
I understand why you insert a blank line (reST wants blank lines around
lists), I don't understand why you indent. Can you explain?
next prev parent reply other threads:[~2020-09-30 8:48 UTC|newest]
Thread overview: 69+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-09-30 4:31 [PATCH v4 00/46] qapi: static typing conversion, pt1 John Snow
2020-09-30 4:31 ` [PATCH v4 01/46] [DO-NOT-MERGE] docs: replace single backtick (`) with double-backtick (``) John Snow
2020-09-30 4:31 ` [PATCH v4 02/46] docs: repair broken references John Snow
2020-09-30 4:31 ` [PATCH v4 03/46] [DO-NOT-MERGE] docs/sphinx: change default role to "any" John Snow
2020-09-30 4:31 ` [PATCH v4 04/46] qapi: modify docstrings to be sphinx-compatible John Snow
2020-09-30 8:47 ` Markus Armbruster [this message]
2020-09-30 17:22 ` John Snow
2020-10-01 8:52 ` Markus Armbruster
2020-10-01 14:48 ` John Snow
2020-10-02 9:19 ` Markus Armbruster
2020-10-02 15:14 ` John Snow
2020-09-30 17:38 ` John Snow
2020-10-01 8:54 ` Markus Armbruster
2020-10-01 14:28 ` John Snow
2020-09-30 4:31 ` [PATCH v4 05/46] [DO-NOT-MERGE] docs: enable sphinx-autodoc for scripts/qapi John Snow
2020-09-30 4:31 ` [PATCH v4 06/46] qapi-gen: Separate arg-parsing from generation John Snow
2020-09-30 4:31 ` [PATCH v4 07/46] qapi: move generator entrypoint into module John Snow
2020-09-30 4:31 ` [PATCH v4 08/46] [DO-NOT-MERGE] docs: add scripts/qapi/main to python manual John Snow
2020-09-30 4:31 ` [PATCH v4 09/46] qapi: Prefer explicit relative imports John Snow
2020-09-30 4:31 ` [PATCH v4 10/46] qapi: Remove wildcard includes John Snow
2020-09-30 4:31 ` [PATCH v4 11/46] qapi: enforce import order/styling with isort John Snow
2020-09-30 4:31 ` [PATCH v4 12/46] qapi: delint using flake8 John Snow
2020-09-30 4:31 ` [PATCH v4 13/46] qapi: add pylintrc John Snow
2020-09-30 4:31 ` [PATCH v4 14/46] qapi/common.py: Remove python compatibility workaround John Snow
2020-09-30 4:31 ` [PATCH v4 15/46] qapi/common.py: Add indent manager John Snow
2020-09-30 4:31 ` [PATCH v4 16/46] qapi/common.py: delint with pylint John Snow
2020-09-30 4:31 ` [PATCH v4 17/46] qapi/common.py: Replace one-letter 'c' variable John Snow
2020-09-30 4:31 ` [PATCH v4 18/46] qapi/common.py: check with pylint John Snow
2020-09-30 4:31 ` [PATCH v4 19/46] qapi/common.py: add type hint annotations John Snow
2020-09-30 4:31 ` [PATCH v4 20/46] qapi/common.py: Convert comments into docstrings, and elaborate John Snow
2020-09-30 4:31 ` [PATCH v4 21/46] qapi/common.py: move build_params into gen.py John Snow
2020-09-30 4:31 ` [PATCH v4 22/46] qapi: establish mypy type-checking baseline John Snow
2020-09-30 4:31 ` [PATCH v4 23/46] qapi/events.py: add type hint annotations John Snow
2020-09-30 4:31 ` [PATCH v4 24/46] qapi/events.py: Move comments into docstrings John Snow
2020-09-30 4:31 ` [PATCH v4 25/46] qapi/commands.py: Don't re-bind to variable of different type John Snow
2020-09-30 4:31 ` [PATCH v4 26/46] qapi/commands.py: add type hint annotations John Snow
2020-09-30 4:31 ` [PATCH v4 27/46] qapi/commands.py: enable checking with mypy John Snow
2020-09-30 4:31 ` [PATCH v4 28/46] qapi/source.py: add type hint annotations John Snow
2020-09-30 4:31 ` [PATCH v4 29/46] qapi/source.py: delint with pylint John Snow
2020-09-30 4:31 ` [PATCH v4 30/46] qapi/gen.py: Fix edge-case of _is_user_module John Snow
2020-09-30 11:03 ` Eduardo Habkost
2020-09-30 4:31 ` [PATCH v4 31/46] qapi/gen.py: add type hint annotations John Snow
2020-09-30 4:31 ` [PATCH v4 32/46] qapi/gen.py: Enable checking with mypy John Snow
2020-09-30 4:31 ` [PATCH v4 33/46] qapi/gen.py: Remove unused parameter John Snow
2020-09-30 4:31 ` [PATCH v4 34/46] qapi/gen.py: update write() to be more idiomatic John Snow
2020-09-30 4:31 ` [PATCH v4 35/46] qapi/gen.py: delint with pylint John Snow
2020-09-30 4:31 ` [PATCH v4 36/46] qapi/introspect.py: assert obj is a dict when features are given John Snow
2020-09-30 11:04 ` Eduardo Habkost
2020-09-30 4:31 ` [PATCH v4 37/46] qapi/instrospect.py: add preliminary type hint annotations John Snow
2020-09-30 18:31 ` Eduardo Habkost
2020-09-30 4:31 ` [PATCH v4 38/46] qapi/introspect.py: add _gen_features helper John Snow
2020-09-30 17:21 ` Eduardo Habkost
2020-09-30 4:31 ` [PATCH v4 39/46] qapi/introspect.py: Unify return type of _make_tree() John Snow
2020-09-30 18:24 ` Eduardo Habkost
2020-09-30 18:32 ` John Snow
2020-09-30 18:57 ` Eduardo Habkost
2020-09-30 19:02 ` John Snow
2020-09-30 4:31 ` [PATCH v4 40/46] qapi/introspect.py: replace 'extra' dict with 'comment' argument John Snow
2020-09-30 18:24 ` Eduardo Habkost
2020-09-30 4:31 ` [PATCH v4 41/46] qapi/introspect.py: create a typed 'Node' data structure John Snow
2020-09-30 18:39 ` Eduardo Habkost
2020-09-30 18:58 ` John Snow
2020-09-30 19:52 ` Eduardo Habkost
2020-10-01 17:59 ` John Snow
2020-09-30 4:31 ` [PATCH v4 42/46] qapi/types.py: add type hint annotations John Snow
2020-09-30 4:31 ` [PATCH v4 43/46] qapi/types.py: remove one-letter variables John Snow
2020-09-30 4:31 ` [PATCH v4 44/46] qapi/visit.py: assert tag_member contains a QAPISchemaEnumType John Snow
2020-09-30 4:31 ` [PATCH v4 45/46] qapi/visit.py: remove unused parameters from gen_visit_object John Snow
2020-09-30 4:31 ` [PATCH v4 46/46] qapi/visit.py: add type hint annotations 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=87wo0bejmy.fsf@dusky.pond.sub.org \
--to=armbru@redhat.com \
--cc=alex.bennee@linaro.org \
--cc=crosa@redhat.com \
--cc=ehabkost@redhat.com \
--cc=jsnow@redhat.com \
--cc=peter.maydell@linaro.org \
--cc=qemu-devel@nongnu.org \
--cc=thuth@redhat.com \
/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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.