Re: [PATCH v3 15/15] python: Fix broken ReST docstrings

[Willian Rampazzo]

On Tue, Jun 29, 2021 at 6:44 PM John Snow <jsnow@redhat.com> wrote:
>
> 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(-)
>

Reviewed-by: Willian Rampazzo <willianr@redhat.com>