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