[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PULL 02/34] qapi: modify docstrings to be sphinx-compatible
From: |
Markus Armbruster |
Subject: |
[PULL 02/34] qapi: modify docstrings to be sphinx-compatible |
Date: |
Sat, 10 Oct 2020 11:54:32 +0200 |
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
- [PULL 00/34] QAPI patches patches for 2020-10-10, Markus Armbruster, 2020/10/10
- [PULL 13/34] qapi/common.py: Replace one-letter 'c' variable, Markus Armbruster, 2020/10/10
- [PULL 03/34] qapi-gen: Separate arg-parsing from generation, Markus Armbruster, 2020/10/10
- [PULL 01/34] docs: repair broken references, Markus Armbruster, 2020/10/10
- [PULL 07/34] qapi: enforce import order/styling with isort, Markus Armbruster, 2020/10/10
- [PULL 08/34] qapi: delint using flake8, Markus Armbruster, 2020/10/10
- [PULL 11/34] qapi/common.py: Add indent manager, Markus Armbruster, 2020/10/10
- [PULL 12/34] qapi/common.py: delint with pylint, Markus Armbruster, 2020/10/10
- [PULL 02/34] qapi: modify docstrings to be sphinx-compatible,
Markus Armbruster <=
- [PULL 15/34] qapi/common.py: add type hint annotations, Markus Armbruster, 2020/10/10
- [PULL 05/34] qapi: Prefer explicit relative imports, Markus Armbruster, 2020/10/10
- [PULL 14/34] qapi/common.py: check with pylint, Markus Armbruster, 2020/10/10
- [PULL 10/34] qapi/common.py: Remove python compatibility workaround, Markus Armbruster, 2020/10/10
- [PULL 04/34] qapi: move generator entrypoint into package, Markus Armbruster, 2020/10/10
- [PULL 06/34] qapi: Remove wildcard includes, Markus Armbruster, 2020/10/10
- [PULL 27/34] qapi/gen.py: Remove unused parameter, Markus Armbruster, 2020/10/10
- [PULL 18/34] qapi: establish mypy type-checking baseline, Markus Armbruster, 2020/10/10
- [PULL 24/34] qapi/source.py: delint with pylint, Markus Armbruster, 2020/10/10
- [PULL 28/34] qapi/gen.py: update write() to be more idiomatic, Markus Armbruster, 2020/10/10