1. Patchew
  2. QEMU
  3. [PATCH v3 00/47] qapi: static typing conversion, pt1
  4. View patch

[PATCH v3 04/47] qapi: modify docstrings to be sphinx-compatible

John Snow posted 47 patches 5 years, 4 months ago
Maintainers: Peter Maydell <peter.maydell@linaro.org>, Cornelia Huck <cohuck@redhat.com>, Eduardo Habkost <ehabkost@redhat.com>, Thomas Huth <thuth@redhat.com>, "Alex Bennée" <alex.bennee@linaro.org>, Cleber Rosa <crosa@redhat.com>, Michael Roth <mdroth@linux.vnet.ibm.com>, Markus Armbruster <armbru@redhat.com>, "Dr. David Alan Gilbert" <dgilbert@redhat.com>, Juan Quintela <quintela@redhat.com>
There is a newer version of this series
[PATCH v3 04/47] qapi: modify docstrings to be sphinx-compatible
Posted by John Snow 5 years, 4 months ago 
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()
 
-    *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 165925ca72..00738cea8c 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -366,10 +366,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:
-- 
2.26.2
Re: [PATCH v3 04/47] qapi: modify docstrings to be sphinx-compatible
Posted by Cleber Rosa 5 years, 4 months ago 
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.
Re: [PATCH v3 04/47] qapi: modify docstrings to be sphinx-compatible
Posted by John Snow 5 years, 4 months ago 
On 9/28/20 11:39 PM, Cleber Rosa wrote:
> 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?
> 

I forget. Must not have been a good reason, then...?

> 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.
> 

I remain unsold on using explicit roles for references in docstrings, 
because I'd like to keep the amount of Sphinx-ese syntax down to a 
minimum if I can. The double backticks are bad enough ...

>> -    *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.
> 

Not entirely correct: the syntax of *args breaks document generation.

(OK, I could make QAPIGenCCode a reference ...)

> - Cleber.
>

Patchew 2.1-devel-b67e4c2

© 2016 - 2026 Red Hat, Inc.