On Fri, Jun 28, 2024, 9:09 AM Markus Armbruster <armbru@redhat.com> wrote:
> John Snow <jsnow@redhat.com> writes:
>
> > Factor out the compatibility parser helper so it can be shared by other
> > directives.
>
> Suggest "Factor out the compatibility parser helper into a base class,
> so it can be shared by other directives."
Sure. Haven't read the other mails yet. I'll make the change if you want a
v3, otherwise feel free to edit.
> >
> > Signed-off-by: John Snow <jsnow@redhat.com>
> > ---
> > docs/sphinx/qapidoc.py | 64 +++++++++++++++++++++++-------------------
> > 1 file changed, 35 insertions(+), 29 deletions(-)
> >
> > diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
> > index efcd84656fa..43dd99e21e6 100644
> > --- a/docs/sphinx/qapidoc.py
> > +++ b/docs/sphinx/qapidoc.py
> > @@ -494,7 +494,41 @@ def visit_module(self, name):
> > super().visit_module(name)
> >
> >
> > -class QAPIDocDirective(Directive):
> > +class NestedDirective(Directive):
> > + def run(self):
> > + raise NotImplementedError
>
> Should this class be abstract?
>
It could be ...
*sneezes*
I plan to delete it by the end of the qapi-domain series anyway, or perhaps
I could even delete it *before* with a dedicated "require sphinx >= 3.x"
miniseries.
Actually, that's probably a really good idea...
> > +
> > + def do_parse(self, rstlist, node):
> > + """
> > + Parse rST source lines and add them to the specified node
> > +
> > + Take the list of rST source lines rstlist, parse them as
> > + rST, and add the resulting docutils nodes as children of node.
> > + The nodes are parsed in a way that allows them to include
> > + subheadings (titles) without confusing the rendering of
> > + anything else.
> > + """
> > + # This is from kerneldoc.py -- it works around an API change in
> > + # Sphinx between 1.6 and 1.7. Unlike kerneldoc.py, we use
> > + # sphinx.util.nodes.nested_parse_with_titles() rather than the
> > + # plain self.state.nested_parse(), and so we can drop the saving
> > + # of title_styles and section_level that kerneldoc.py does,
> > + # because nested_parse_with_titles() does that for us.
> > + if USE_SSI:
> > + with switch_source_input(self.state, rstlist):
> > + nested_parse_with_titles(self.state, rstlist, node)
> > + else:
> > + save = self.state.memo.reporter
> > + self.state.memo.reporter = AutodocReporter(
> > + rstlist, self.state.memo.reporter
> > + )
> > + try:
> > + nested_parse_with_titles(self.state, rstlist, node)
> > + finally:
> > + self.state.memo.reporter = save
> > +
> > +
> > +class QAPIDocDirective(NestedDirective):
> > """Extract documentation from the specified QAPI .json file"""
> >
> > required_argument = 1
> > @@ -532,34 +566,6 @@ def run(self):
> > # so they are displayed nicely to the user
> > raise ExtensionError(str(err)) from err
> >
> > - def do_parse(self, rstlist, node):
> > - """Parse rST source lines and add them to the specified node
> > -
> > - Take the list of rST source lines rstlist, parse them as
> > - rST, and add the resulting docutils nodes as children of node.
> > - The nodes are parsed in a way that allows them to include
> > - subheadings (titles) without confusing the rendering of
> > - anything else.
> > - """
> > - # This is from kerneldoc.py -- it works around an API change in
> > - # Sphinx between 1.6 and 1.7. Unlike kerneldoc.py, we use
> > - # sphinx.util.nodes.nested_parse_with_titles() rather than the
> > - # plain self.state.nested_parse(), and so we can drop the saving
> > - # of title_styles and section_level that kerneldoc.py does,
> > - # because nested_parse_with_titles() does that for us.
> > - if USE_SSI:
> > - with switch_source_input(self.state, rstlist):
> > - nested_parse_with_titles(self.state, rstlist, node)
> > - else:
> > - save = self.state.memo.reporter
> > - self.state.memo.reporter = AutodocReporter(
> > - rstlist, self.state.memo.reporter
> > - )
> > - try:
> > - nested_parse_with_titles(self.state, rstlist, node)
> > - finally:
> > - self.state.memo.reporter = save
> > -
> >
> > def setup(app):
> > """Register qapi-doc directive with Sphinx"""
>
> Reviewed-by: Markus Armbruster <armbru@redhat.com>
>
>