| Message ID | 20200925002900.465855-6-jsnow@redhat.com |
|---|---|
| State | New |
| Headers | show |
| Series | qapi: static typing conversion, pt1 | expand |
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>
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
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.
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 --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):
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(-)