diff mbox series

[v3,05/47] qapi/doc.py: Change code templates from function to string

Message ID 20200925002900.465855-6-jsnow@redhat.com
State New
Headers show
Series qapi: static typing conversion, pt1 | expand

Commit Message

John Snow Sept. 25, 2020, 12:28 a.m. UTC
For whatever reason, when these are stored as functions instead of
strings, it confuses sphinx-autodoc into believing them to be
docstrings, and it chokes on the syntax.

Keeping them as dumb strings instead avoids the problem.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 scripts/qapi/doc.py | 40 ++++++++++++++++++++--------------------
 1 file changed, 20 insertions(+), 20 deletions(-)

Comments

Markus Armbruster Sept. 25, 2020, 8:59 a.m. UTC | #1
John Snow <jsnow@redhat.com> writes:

> For whatever reason, when these are stored as functions instead of
> strings, it confuses sphinx-autodoc into believing them to be
> docstrings, and it chokes on the syntax.
>
> Keeping them as dumb strings instead avoids the problem.
>
> Signed-off-by: John Snow <jsnow@redhat.com>

Quoting my review of the patch that added it: "This .format business is
perhaps a bit too clever.  But let's move on."

doc.py is about to be replaced, obsoleting this patch.  Regardless:
Reviewed-by: Markus Armbruster <armbru@redhat.com>
John Snow Sept. 25, 2020, 2:23 p.m. UTC | #2
On 9/25/20 4:59 AM, Markus Armbruster wrote:
> John Snow <jsnow@redhat.com> writes:
> 
>> For whatever reason, when these are stored as functions instead of
>> strings, it confuses sphinx-autodoc into believing them to be
>> docstrings, and it chokes on the syntax.
>>
>> Keeping them as dumb strings instead avoids the problem.
>>
>> Signed-off-by: John Snow <jsnow@redhat.com>
> 
> Quoting my review of the patch that added it: "This .format business is
> perhaps a bit too clever.  But let's move on."
> 

It seems perfectly fine, and I have no real explanation for why it 
confuses autodoc.

I think autodoc is using regex that it maybe shouldn't be to identify 
some constructs instead of the proper Python AST. I looked extremely 
briefly but made the assessment it wasn't going to be quick.

> doc.py is about to be replaced, obsoleting this patch.  Regardless:
> Reviewed-by: Markus Armbruster <armbru@redhat.com>
> 

Yes, understood -- until such time as it is actually deleted, I am 
keeping it updated with the style I am trying to enforce just to make my 
own life simpler.

It's no problem to just trash it when the time comes, but in this case I 
wanted to explore what stopped us from using Sphinx autodoc earnestly -- 
and it just so happened that this was the sticking point.

Thanks for looking!

--js
Cleber Rosa Sept. 29, 2020, 3:51 a.m. UTC | #3
On Thu, Sep 24, 2020 at 08:28:18PM -0400, John Snow wrote:
> For whatever reason, when these are stored as functions instead of

> strings, it confuses sphinx-autodoc into believing them to be

> docstrings, and it chokes on the syntax.

>


Interesting...

> Keeping them as dumb strings instead avoids the problem.

>


I actually think it's a more honest approach, and easier to read.

> Signed-off-by: John Snow <jsnow@redhat.com>

> ---

>  scripts/qapi/doc.py | 40 ++++++++++++++++++++--------------------

>  1 file changed, 20 insertions(+), 20 deletions(-)

> 

> diff --git a/scripts/qapi/doc.py b/scripts/qapi/doc.py

> index c41e9d29f5..d12eda9e1e 100644

> --- a/scripts/qapi/doc.py

> +++ b/scripts/qapi/doc.py

> @@ -8,26 +8,26 @@

>  from qapi.gen import QAPIGenDoc, QAPISchemaVisitor

>  

>  

> -MSG_FMT = """

> +_MSG = '''

>  @deftypefn {type} {{}} {name}

>  

>  {body}{members}{features}{sections}

>  @end deftypefn

>  

> -""".format

> +'''

>


I know it doesn't make syntactic difference, but is there a reson for
also changing the quote style?

- Cleber.
John Snow Sept. 29, 2020, 6:25 p.m. UTC | #4
On 9/28/20 11:51 PM, Cleber Rosa wrote:
> On Thu, Sep 24, 2020 at 08:28:18PM -0400, John Snow wrote:

>> For whatever reason, when these are stored as functions instead of

>> strings, it confuses sphinx-autodoc into believing them to be

>> docstrings, and it chokes on the syntax.

>>

> 

> Interesting...

> 

>> Keeping them as dumb strings instead avoids the problem.

>>

> 

> I actually think it's a more honest approach, and easier to read.

> 

>> Signed-off-by: John Snow <jsnow@redhat.com>

>> ---

>>   scripts/qapi/doc.py | 40 ++++++++++++++++++++--------------------

>>   1 file changed, 20 insertions(+), 20 deletions(-)

>>

>> diff --git a/scripts/qapi/doc.py b/scripts/qapi/doc.py

>> index c41e9d29f5..d12eda9e1e 100644

>> --- a/scripts/qapi/doc.py

>> +++ b/scripts/qapi/doc.py

>> @@ -8,26 +8,26 @@

>>   from qapi.gen import QAPIGenDoc, QAPISchemaVisitor

>>   

>>   

>> -MSG_FMT = """

>> +_MSG = '''

>>   @deftypefn {type} {{}} {name}

>>   

>>   {body}{members}{features}{sections}

>>   @end deftypefn

>>   

>> -""".format

>> +'''

>>

> 

> I know it doesn't make syntactic difference, but is there a reson for

> also changing the quote style?

> 

> - Cleber.

> 


Was just trying to differentiate it from docstrings to see if it helped. 
It didn't, but it also didn't hurt, so I left it.

Luckily, this patch won't matter after Peter Maydell's series goes in, 
so whatever!
diff mbox series

Patch

diff --git a/scripts/qapi/doc.py b/scripts/qapi/doc.py
index c41e9d29f5..d12eda9e1e 100644
--- a/scripts/qapi/doc.py
+++ b/scripts/qapi/doc.py
@@ -8,26 +8,26 @@ 
 from qapi.gen import QAPIGenDoc, QAPISchemaVisitor
 
 
-MSG_FMT = """
+_MSG = '''
 @deftypefn {type} {{}} {name}
 
 {body}{members}{features}{sections}
 @end deftypefn
 
-""".format
+'''
 
-TYPE_FMT = """
+_TYPE = '''
 @deftp {{{type}}} {name}
 
 {body}{members}{features}{sections}
 @end deftp
 
-""".format
+'''
 
-EXAMPLE_FMT = """@example
+_EXAMPLE = '''@example
 {code}
 @end example
-""".format
+'''
 
 
 def subst_strong(doc):
@@ -57,7 +57,7 @@  def texi_example(doc):
     # function to subst_special() or subs_texi_special().  If we do that, we
     # need to delay it until after subst_vars() in texi_format().
     doc = subst_braces(doc).strip('\n')
-    return EXAMPLE_FMT(code=doc)
+    return _EXAMPLE.format(code=doc)
 
 
 def texi_format(doc):
@@ -90,7 +90,7 @@  def texi_format(doc):
         # Make sure to update section "Documentation markup" in
         # docs/devel/qapi-code-gen.txt when fixing this.
         if line.startswith('| '):
-            line = EXAMPLE_FMT(code=line[2:])
+            line = _EXAMPLE.format(code=line[2:])
         elif line.startswith('= '):
             line = '@section ' + line[2:]
         elif line.startswith('== '):
@@ -217,21 +217,21 @@  def texi_sections(doc, ifcond):
 
 
 def texi_type(typ, doc, ifcond, members):
-    return TYPE_FMT(type=typ,
-                    name=doc.symbol,
-                    body=texi_body(doc),
-                    members=members,
-                    features=texi_features(doc),
-                    sections=texi_sections(doc, ifcond))
+    return _TYPE.format(type=typ,
+                        name=doc.symbol,
+                        body=texi_body(doc),
+                        members=members,
+                        features=texi_features(doc),
+                        sections=texi_sections(doc, ifcond))
 
 
 def texi_msg(typ, doc, ifcond, members):
-    return MSG_FMT(type=typ,
-                   name=doc.symbol,
-                   body=texi_body(doc),
-                   members=members,
-                   features=texi_features(doc),
-                   sections=texi_sections(doc, ifcond))
+    return _MSG.format(type=typ,
+                       name=doc.symbol,
+                       body=texi_body(doc),
+                       members=members,
+                       features=texi_features(doc),
+                       sections=texi_sections(doc, ifcond))
 
 
 class QAPISchemaGenDocVisitor(QAPISchemaVisitor):