qemu-devel.nongnu.org archive mirror
 help / color / mirror / Atom feed
From: Markus Armbruster <armbru@redhat.com>
To: qemu-devel@nongnu.org
Cc: peter.maydell@linaro.org, John Snow <jsnow@redhat.com>
Subject: [PULL 02/34] qapi: modify docstrings to be sphinx-compatible
Date: Sat, 10 Oct 2020 11:54:32 +0200	[thread overview]
Message-ID: <20201010095504.796182-3-armbru@redhat.com> (raw)
In-Reply-To: <20201010095504.796182-1-armbru@redhat.com>

From: John Snow <jsnow@redhat.com>

A precise style guide and a package-wide overhaul is forthcoming pending
further discussion and consensus. For now, merely avoid obvious errors
that cause Sphinx documentation build problems, using a style loosely
based on PEP 257 and Sphinx Autodoc. It is chosen for interoperability
with our existing Sphinx framework, and because it has loose recognition
in the Pycharm IDE.

See also:

https://www.python.org/dev/peps/pep-0257/
https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#info-field-lists
Signed-off-by: John Snow <jsnow@redhat.com>
Message-Id: <20201009161558.107041-3-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 scripts/qapi/gen.py | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/scripts/qapi/gen.py b/scripts/qapi/gen.py
index ca66c82b5b..dc7b94aa11 100644
--- a/scripts/qapi/gen.py
+++ b/scripts/qapi/gen.py
@@ -154,9 +154,11 @@ class QAPIGenH(QAPIGenC):
 
 @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()` / `end_if()`.
 
-    *args: any number of QAPIGenCCode
+    :param ifcond: A list of conditionals, passed to `start_if()`.
+    :param args: any number of `QAPIGenCCode`.
 
     Example::
 
-- 
2.26.2



  parent reply	other threads:[~2020-10-10 10:08 UTC|newest]

Thread overview: 39+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-10-10  9:54 [PULL 00/34] QAPI patches patches for 2020-10-10 Markus Armbruster
2020-10-10  9:54 ` [PULL 01/34] docs: repair broken references Markus Armbruster
2020-10-10  9:54 ` Markus Armbruster [this message]
2020-10-10  9:54 ` [PULL 03/34] qapi-gen: Separate arg-parsing from generation Markus Armbruster
2020-10-10  9:54 ` [PULL 04/34] qapi: move generator entrypoint into package Markus Armbruster
2020-10-10  9:54 ` [PULL 05/34] qapi: Prefer explicit relative imports Markus Armbruster
2020-10-10  9:54 ` [PULL 06/34] qapi: Remove wildcard includes Markus Armbruster
2020-10-10  9:54 ` [PULL 07/34] qapi: enforce import order/styling with isort Markus Armbruster
2020-10-10  9:54 ` [PULL 08/34] qapi: delint using flake8 Markus Armbruster
2020-10-10  9:54 ` [PULL 09/34] qapi: add pylintrc Markus Armbruster
2020-10-10  9:54 ` [PULL 10/34] qapi/common.py: Remove python compatibility workaround Markus Armbruster
2020-10-10  9:54 ` [PULL 11/34] qapi/common.py: Add indent manager Markus Armbruster
2020-10-10  9:54 ` [PULL 12/34] qapi/common.py: delint with pylint Markus Armbruster
2020-10-10  9:54 ` [PULL 13/34] qapi/common.py: Replace one-letter 'c' variable Markus Armbruster
2020-10-10  9:54 ` [PULL 14/34] qapi/common.py: check with pylint Markus Armbruster
2020-10-10  9:54 ` [PULL 15/34] qapi/common.py: add type hint annotations Markus Armbruster
2020-10-10  9:54 ` [PULL 16/34] qapi/common.py: Convert comments into docstrings, and elaborate Markus Armbruster
2020-10-10  9:54 ` [PULL 17/34] qapi/common.py: move build_params into gen.py Markus Armbruster
2020-10-10  9:54 ` [PULL 18/34] qapi: establish mypy type-checking baseline Markus Armbruster
2020-10-10  9:54 ` [PULL 19/34] qapi/events.py: add type hint annotations Markus Armbruster
2020-10-10  9:54 ` [PULL 20/34] qapi/events.py: Move comments into docstrings Markus Armbruster
2020-10-10  9:54 ` [PULL 21/34] qapi/commands.py: Don't re-bind to variable of different type Markus Armbruster
2020-10-10  9:54 ` [PULL 22/34] qapi/commands.py: add type hint annotations Markus Armbruster
2020-10-10  9:54 ` [PULL 23/34] qapi/source.py: " Markus Armbruster
2020-10-10  9:54 ` [PULL 24/34] qapi/source.py: delint with pylint Markus Armbruster
2020-10-10  9:54 ` [PULL 25/34] qapi/gen: Make _is_user_module() return bool Markus Armbruster
2020-10-10  9:54 ` [PULL 26/34] qapi/gen.py: add type hint annotations Markus Armbruster
2020-10-10  9:54 ` [PULL 27/34] qapi/gen.py: Remove unused parameter Markus Armbruster
2020-10-10  9:54 ` [PULL 28/34] qapi/gen.py: update write() to be more idiomatic Markus Armbruster
2020-10-10  9:54 ` [PULL 29/34] qapi/gen.py: delint with pylint Markus Armbruster
2020-10-10  9:55 ` [PULL 30/34] qapi/types.py: add type hint annotations Markus Armbruster
2020-10-10  9:55 ` [PULL 31/34] qapi/types.py: remove one-letter variables Markus Armbruster
2020-10-10  9:55 ` [PULL 32/34] qapi/visit.py: assert tag_member contains a QAPISchemaEnumType Markus Armbruster
2020-10-10  9:55 ` [PULL 33/34] qapi/visit.py: remove unused parameters from gen_visit_object Markus Armbruster
2020-10-10  9:55 ` [PULL 34/34] qapi/visit.py: add type hint annotations Markus Armbruster
2020-10-12 11:31 ` [PULL 00/34] QAPI patches patches for 2020-10-10 Peter Maydell
2020-10-18  7:29 ` Philippe Mathieu-Daudé
2020-10-19  8:09   ` Markus Armbruster
2020-10-19 14:34   ` 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=20201010095504.796182-3-armbru@redhat.com \
    --to=armbru@redhat.com \
    --cc=jsnow@redhat.com \
    --cc=peter.maydell@linaro.org \
    --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).