[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH v4 04/46] qapi: modify docstrings to be sphinx-compatible
From: |
Markus Armbruster |
Subject: |
Re: [PATCH v4 04/46] qapi: modify docstrings to be sphinx-compatible |
Date: |
Wed, 30 Sep 2020 10:47:17 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/27.1 (gnu/linux) |
John Snow <jsnow@redhat.com> writes:
> I did not say "sphinx beautiful", just "sphinx compatible". They will
> not throw errors when parsed and interpreted as ReST.
"Bang on the keyboard until Sphinx doesn't throw errors anymore" might
be good enough for a certain kind of mathematician, but a constructive
solution needs a bit more direction. Is there a specification to
follow? Other useful resources?
>
> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
> scripts/qapi/gen.py | 6 ++++--
> scripts/qapi/parser.py | 9 +++++----
> 2 files changed, 9 insertions(+), 6 deletions(-)
>
> diff --git a/scripts/qapi/gen.py b/scripts/qapi/gen.py
> index ca66c82b5b8..fc19b2aeb9b 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` and
> `end_if`.
Sadly, the fact that start_if() and end_if() are functions isn't
immediately obvious anymore.
I've seen :func:`start_if` elsewhere. Is this something we should or
want to use?
>
> - *args: any number of QAPIGenCCode
> + :param ifcond: List of conditionals
> + :param args: any number of `QAPIGenCCode`.
>
> Example::
>
> diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
> index 9d1a3e2eea9..02983979965 100644
> --- a/scripts/qapi/parser.py
> +++ b/scripts/qapi/parser.py
> @@ -381,10 +381,11 @@ def append(self, line):
>
> The way that the line is dealt with depends on which part of
> the documentation we're parsing right now:
> - * The body section: ._append_line is ._append_body_line
> - * An argument section: ._append_line is ._append_args_line
> - * A features section: ._append_line is ._append_features_line
> - * An additional section: ._append_line is ._append_various_line
> +
> + * The body section: ._append_line is ._append_body_line
> + * An argument section: ._append_line is ._append_args_line
> + * A features section: ._append_line is ._append_features_line
> + * An additional section: ._append_line is ._append_various_line
> """
> line = line[1:]
> if not line:
I understand why you insert a blank line (reST wants blank lines around
lists), I don't understand why you indent. Can you explain?
- [PATCH v4 00/46] qapi: static typing conversion, pt1, John Snow, 2020/09/30
- [PATCH v4 02/46] docs: repair broken references, John Snow, 2020/09/30
- [PATCH v4 03/46] [DO-NOT-MERGE] docs/sphinx: change default role to "any", John Snow, 2020/09/30
- [PATCH v4 04/46] qapi: modify docstrings to be sphinx-compatible, John Snow, 2020/09/30
- Re: [PATCH v4 04/46] qapi: modify docstrings to be sphinx-compatible,
Markus Armbruster <=
- [PATCH v4 01/46] [DO-NOT-MERGE] docs: replace single backtick (`) with double-backtick (``), John Snow, 2020/09/30
- [PATCH v4 05/46] [DO-NOT-MERGE] docs: enable sphinx-autodoc for scripts/qapi, John Snow, 2020/09/30
- [PATCH v4 07/46] qapi: move generator entrypoint into module, John Snow, 2020/09/30
- [PATCH v4 09/46] qapi: Prefer explicit relative imports, John Snow, 2020/09/30
- [PATCH v4 06/46] qapi-gen: Separate arg-parsing from generation, John Snow, 2020/09/30
- [PATCH v4 08/46] [DO-NOT-MERGE] docs: add scripts/qapi/main to python manual, John Snow, 2020/09/30
- [PATCH v4 11/46] qapi: enforce import order/styling with isort, John Snow, 2020/09/30
- [PATCH v4 10/46] qapi: Remove wildcard includes, John Snow, 2020/09/30