Re: [PATCH v4 04/46] qapi: modify docstrings to be sphinx-compatible

[Markus Armbruster]

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?