This patch *doesn't* update all of the docstring standards across the
QEMU package directory to make our docstring usage consistent. It
*doesn't* fix the formatting to make it look pretty or reasonable in
generated output. It *does* fix a few small instances where Sphinx would
emit a build warning because of malformed ReST -- If we built our Python
docs with Sphinx.
Signed-off-by: John Snow <jsnow@redhat.com>
---
You'll have to take my word for it for now, or, to test that (ugly
though it may be) a theoretical Sphinx build would produce no build
errors:
cd ~/src/qemu/python
sphinx-apidoc --separate --private --no-toc --module-first \
--implicit-namespaces --full --ext-intersphinx --ext-coverage \
--ext-viewcode qemu/ -o docs/
sed -i '1s|^|import os; import sys; sys.path.insert(0,
os.path.abspath("../"))\n|' docs/conf.py
make -C docs html
rm -rf docs/
I am preparing to add Sphinx, but need to fix these annoyances first so
that regressions are easy to spot as fixes are applied across the
tree. I plan to use my forthcoming Asynchronous QMP series as a test
pilot for documenting our docstring standards. Assuming it goes well, I
will update the docstrings elsewhere in this package at that time.
Signed-off-by: John Snow <jsnow@redhat.com>
---
python/qemu/machine/__init__.py | 6 +++---
python/qemu/machine/machine.py | 3 ++-
python/qemu/qmp/__init__.py | 1 +
python/qemu/qmp/qom_common.py | 2 +-
python/qemu/utils/accel.py | 2 +-
5 files changed, 8 insertions(+), 6 deletions(-)
diff --git a/python/qemu/machine/__init__.py b/python/qemu/machine/__init__.py
index 728f27adbe..9ccd58ef14 100644
--- a/python/qemu/machine/__init__.py
+++ b/python/qemu/machine/__init__.py
@@ -4,10 +4,10 @@
This library provides a few high-level classes for driving QEMU from a
test suite, not intended for production use.
-- QEMUMachine: Configure and Boot a QEMU VM
- - QEMUQtestMachine: VM class, with a qtest socket.
+ | QEMUQtestProtocol: send/receive qtest messages.
+ | QEMUMachine: Configure and Boot a QEMU VM
+ | +-- QEMUQtestMachine: VM class, with a qtest socket.
-- QEMUQtestProtocol: Connect to, send/receive qtest messages.
"""
# Copyright (C) 2020-2021 John Snow for Red Hat Inc.
diff --git a/python/qemu/machine/machine.py b/python/qemu/machine/machine.py
index e3345dfa1b..d47ab3d896 100644
--- a/python/qemu/machine/machine.py
+++ b/python/qemu/machine/machine.py
@@ -545,7 +545,8 @@ def set_qmp_monitor(self, enabled: bool = True) -> None:
@param enabled: if False, qmp monitor options will be removed from
the base arguments of the resulting QEMU command
line. Default is True.
- @note: call this function before launch().
+
+ .. note:: Call this function before launch().
"""
self._qmp_set = enabled
diff --git a/python/qemu/qmp/__init__.py b/python/qemu/qmp/__init__.py
index 376954cb6d..269516a79b 100644
--- a/python/qemu/qmp/__init__.py
+++ b/python/qemu/qmp/__init__.py
@@ -279,6 +279,7 @@ def accept(self, timeout: Optional[float] = 15.0) ->
QMPMessage:
None). The value passed will set the behavior of the
underneath QMP socket as described in [1].
Default value is set to 15.0.
+
@return QMP greeting dict
@raise OSError on socket connection errors
@raise QMPConnectError if the greeting is not received
diff --git a/python/qemu/qmp/qom_common.py b/python/qemu/qmp/qom_common.py
index f82b16772d..a59ae1a2a1 100644
--- a/python/qemu/qmp/qom_common.py
+++ b/python/qemu/qmp/qom_common.py
@@ -156,7 +156,7 @@ def command_runner(
"""
Run a fully-parsed subcommand, with error-handling for the CLI.
- :return: The return code from `.run()`.
+ :return: The return code from `run()`.
"""
try:
cmd = cls(args)
diff --git a/python/qemu/utils/accel.py b/python/qemu/utils/accel.py
index 297933df2a..386ff640ca 100644
--- a/python/qemu/utils/accel.py
+++ b/python/qemu/utils/accel.py
@@ -36,7 +36,7 @@ def list_accel(qemu_bin: str) -> List[str]:
List accelerators enabled in the QEMU binary.
@param qemu_bin (str): path to the QEMU binary.
- @raise Exception: if failed to run `qemu -accel help`
+ @raise Exception: if failed to run ``qemu -accel help``
@return a list of accelerator names.
"""
if not qemu_bin: