All of lore.kernel.org
 help / color / mirror / Atom feed
From: John Snow <jsnow@redhat.com>
To: qemu-devel@nongnu.org
Cc: Michael Roth <mdroth@linux.vnet.ibm.com>,
	John Snow <jsnow@redhat.com>,
	Markus Armbruster <armbru@redhat.com>,
	Eduardo Habkost <ehabkost@redhat.com>,
	Cleber Rosa <crosa@redhat.com>
Subject: [PATCH v6 02/36] qapi: modify docstrings to be sphinx-compatible
Date: Fri,  9 Oct 2020 12:15:24 -0400	[thread overview]
Message-ID: <20201009161558.107041-3-jsnow@redhat.com> (raw)
In-Reply-To: <20201009161558.107041-1-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>
---
 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 ca66c82b5b8..dc7b94aa115 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()` / `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-09 16:29 UTC|newest]

Thread overview: 45+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-10-09 16:15 [PATCH v6 00/36] qapi: static typing conversion, pt1 John Snow
2020-10-09 16:15 ` [PATCH v6 01/36] docs: repair broken references John Snow
2020-10-09 16:15 ` John Snow [this message]
2020-10-09 16:15 ` [PATCH v6 03/36] qapi-gen: Separate arg-parsing from generation John Snow
2020-10-09 17:26   ` Markus Armbruster
2020-10-12 14:57     ` John Snow
2020-10-19  7:33       ` Markus Armbruster
2020-10-09 16:15 ` [PATCH v6 04/36] qapi: move generator entrypoint into package John Snow
2020-10-09 16:15 ` [PATCH v6 05/36] qapi: Prefer explicit relative imports John Snow
2020-10-09 16:15 ` [PATCH v6 06/36] qapi: Remove wildcard includes John Snow
2020-10-09 16:15 ` [PATCH v6 07/36] qapi: enforce import order/styling with isort John Snow
2020-10-09 16:15 ` [PATCH v6 08/36] qapi: delint using flake8 John Snow
2020-10-09 16:15 ` [PATCH v6 09/36] qapi: add pylintrc John Snow
2020-10-09 16:15 ` [PATCH v6 10/36] qapi/common.py: Remove python compatibility workaround John Snow
2020-10-09 16:15 ` [PATCH v6 11/36] qapi/common.py: Add indent manager John Snow
2020-10-09 16:15 ` [PATCH v6 12/36] qapi/common.py: delint with pylint John Snow
2020-10-09 16:15 ` [PATCH v6 13/36] qapi/common.py: Replace one-letter 'c' variable John Snow
2020-10-09 16:15 ` [PATCH v6 14/36] qapi/common.py: check with pylint John Snow
2020-10-09 16:15 ` [PATCH v6 15/36] qapi/common.py: add type hint annotations John Snow
2020-10-09 16:15 ` [PATCH v6 16/36] qapi/common.py: Convert comments into docstrings, and elaborate John Snow
2020-10-09 16:15 ` [PATCH v6 17/36] qapi/common.py: move build_params into gen.py John Snow
2020-10-09 16:15 ` [PATCH v6 18/36] qapi: establish mypy type-checking baseline John Snow
2020-10-09 16:15 ` [PATCH v6 19/36] qapi/events.py: add type hint annotations John Snow
2020-10-09 16:15 ` [PATCH v6 20/36] qapi/events.py: Move comments into docstrings John Snow
2020-10-09 16:15 ` [PATCH v6 21/36] qapi/commands.py: Don't re-bind to variable of different type John Snow
2020-10-09 16:15 ` [PATCH v6 22/36] qapi/commands.py: add type hint annotations John Snow
2020-10-09 16:15 ` [PATCH v6 23/36] qapi/commands.py: enable checking with mypy John Snow
2020-10-09 16:15 ` [PATCH v6 24/36] qapi/source.py: add type hint annotations John Snow
2020-10-09 16:15 ` [PATCH v6 25/36] qapi/source.py: delint with pylint John Snow
2020-10-09 16:15 ` [PATCH v6 26/36] qapi/gen.py: Fix edge-case of _is_user_module John Snow
2020-10-09 17:26   ` Markus Armbruster
2020-10-09 17:39     ` Eduardo Habkost
2020-10-10  6:57       ` Markus Armbruster
2020-10-09 16:15 ` [PATCH v6 27/36] qapi/gen.py: add type hint annotations John Snow
2020-10-09 16:15 ` [PATCH v6 28/36] qapi/gen.py: Enable checking with mypy John Snow
2020-10-09 16:15 ` [PATCH v6 29/36] qapi/gen.py: Remove unused parameter John Snow
2020-10-09 16:15 ` [PATCH v6 30/36] qapi/gen.py: update write() to be more idiomatic John Snow
2020-10-09 16:15 ` [PATCH v6 31/36] qapi/gen.py: delint with pylint John Snow
2020-10-09 16:15 ` [PATCH v6 32/36] qapi/types.py: add type hint annotations John Snow
2020-10-09 16:15 ` [PATCH v6 33/36] qapi/types.py: remove one-letter variables John Snow
2020-10-09 16:15 ` [PATCH v6 34/36] qapi/visit.py: assert tag_member contains a QAPISchemaEnumType John Snow
2020-10-09 16:15 ` [PATCH v6 35/36] qapi/visit.py: remove unused parameters from gen_visit_object John Snow
2020-10-09 16:15 ` [PATCH v6 36/36] qapi/visit.py: add type hint annotations John Snow
2020-10-10  9:43 ` [PATCH v6 00/36] qapi: static typing conversion, pt1 Markus Armbruster
2020-10-12 14:19   ` 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=20201009161558.107041-3-jsnow@redhat.com \
    --to=jsnow@redhat.com \
    --cc=armbru@redhat.com \
    --cc=crosa@redhat.com \
    --cc=ehabkost@redhat.com \
    --cc=mdroth@linux.vnet.ibm.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 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.