[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH v3 04/47] qapi: modify docstrings to be sphinx-compatible
From: |
Cleber Rosa |
Subject: |
Re: [PATCH v3 04/47] qapi: modify docstrings to be sphinx-compatible |
Date: |
Mon, 28 Sep 2020 23:39:46 -0400 |
On Thu, Sep 24, 2020 at 08:28:17PM -0400, John Snow wrote:
> I did not say "sphinx beautiful", just "sphinx compatible". They will
> not throw errors when parsed and interpreted as ReST.
>
> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
> scripts/qapi/doc.py | 10 +++++-----
> scripts/qapi/gen.py | 6 ++++--
> scripts/qapi/parser.py | 9 +++++----
> 3 files changed, 14 insertions(+), 11 deletions(-)
>
> diff --git a/scripts/qapi/doc.py b/scripts/qapi/doc.py
> index 92f584edcf..c41e9d29f5 100644
> --- a/scripts/qapi/doc.py
> +++ b/scripts/qapi/doc.py
> @@ -65,11 +65,11 @@ def texi_format(doc):
> Format documentation
>
> Lines starting with:
> - - |: generates an @example
> - - =: generates @section
> - - ==: generates @subsection
> - - 1. or 1): generates an @enumerate @item
> - - */-: generates an @itemize list
> + - ``|:`` generates an @example
> + - ``=:`` generates @section
> + - ``==:`` generates @subsection
> + - ``1.`` or ``1):`` generates an @enumerate @item
> + - ``*/-:`` generates an @itemize list
> """
> ret = ''
> doc = subst_braces(doc)
> diff --git a/scripts/qapi/gen.py b/scripts/qapi/gen.py
> index bf5552a4e7..3d25a8cff4 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 to wrap with start_if()/end_if()
>
If you're making it compatible, why not take the time to give
backticks to start_if and end_if?
Bonus points for setting the "meth" role, but not lost points for not
doing it, as I understand this is beyond what you're attempting at
this time.
> - *args: any number of QAPIGenCCode
> + :param ifcond: List of conditionals
> + :param args: any number of QAPIGenCCode
>
I would argue that this is not a strict sphinx compatibility change,
but a fix to a broken docstring.
- Cleber.
signature.asc
Description: PGP signature
- Re: [PATCH v3 03/47] [DO-NOT-MERGE] docs/sphinx: change default role to "any", (continued)
- [PATCH v3 02/47] [DO-NOT-MERGE] docs: repair broken references, John Snow, 2020/09/24
- [PATCH v3 07/47] qapi-gen: Separate arg-parsing from generation, John Snow, 2020/09/24
- [PATCH v3 06/47] [DO-NOT-MERGE] docs: enable sphinx-autodoc for scripts/qapi, John Snow, 2020/09/24
- [PATCH v3 04/47] qapi: modify docstrings to be sphinx-compatible, John Snow, 2020/09/24
- Re: [PATCH v3 04/47] qapi: modify docstrings to be sphinx-compatible,
Cleber Rosa <=
- [PATCH v3 08/47] qapi: move generator entrypoint into module, John Snow, 2020/09/24
- [PATCH v3 01/47] [DO-NOT-MERGE] docs: replace single backtick (`) with double-backtick (``), John Snow, 2020/09/24
- [PATCH v3 11/47] qapi: Remove wildcard includes, John Snow, 2020/09/24
- [PATCH v3 09/47] [DO-NOT-MERGE] docs: add scripts/qapi/main to python manual, John Snow, 2020/09/24
- [PATCH v3 12/47] qapi: enforce import order/styling with isort, John Snow, 2020/09/24