[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH v6 02/36] qapi: modify docstrings to be sphinx-compatible
From: |
John Snow |
Subject: |
[PATCH v6 02/36] qapi: modify docstrings to be sphinx-compatible |
Date: |
Fri, 9 Oct 2020 12:15:24 -0400 |
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
- [PATCH v6 00/36] qapi: static typing conversion, pt1, John Snow, 2020/10/09
- [PATCH v6 04/36] qapi: move generator entrypoint into package, John Snow, 2020/10/09
- [PATCH v6 08/36] qapi: delint using flake8, John Snow, 2020/10/09
- [PATCH v6 06/36] qapi: Remove wildcard includes, John Snow, 2020/10/09
- [PATCH v6 05/36] qapi: Prefer explicit relative imports, John Snow, 2020/10/09
- [PATCH v6 07/36] qapi: enforce import order/styling with isort, John Snow, 2020/10/09
- [PATCH v6 09/36] qapi: add pylintrc, John Snow, 2020/10/09