[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH v2 14/21] docs/qapidoc: factor out do_parse()
From: |
Markus Armbruster |
Subject: |
Re: [PATCH v2 14/21] docs/qapidoc: factor out do_parse() |
Date: |
Fri, 28 Jun 2024 15:08:48 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) |
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."
>
> 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?
> +
> + 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>
- Re: [PATCH v2 07/21] docs/qapidoc: fix nested parsing under untagged sections, (continued)
- [PATCH v2 08/21] qapi: fix non-compliant JSON examples, John Snow, 2024/06/26
- [PATCH v2 09/21] qapi: nail down convention that Errors sections are lists, John Snow, 2024/06/26
- [PATCH v2 11/21] qapi: update prose in note blocks, John Snow, 2024/06/26
- [PATCH v2 10/21] qapi: convert "Note" sections to plain rST, John Snow, 2024/06/26
- [PATCH v2 12/21] qapi: add markup to note blocks, John Snow, 2024/06/26
- [PATCH v2 13/21] qapi/parser: don't parse rST markup as section headers, John Snow, 2024/06/26
- [PATCH v2 14/21] docs/qapidoc: factor out do_parse(), John Snow, 2024/06/26
- Re: [PATCH v2 14/21] docs/qapidoc: factor out do_parse(),
Markus Armbruster <=
- [PATCH v2 15/21] docs/qapidoc: create qmp-example directive, John Snow, 2024/06/26
- [PATCH v2 18/21] qapi: convert "Example" sections without titles, John Snow, 2024/06/26
- [PATCH v2 19/21] qapi: convert "Example" sections with titles, John Snow, 2024/06/26
- [PATCH v2 17/21] docs/sphinx: add CSS styling for qmp-example directive, John Snow, 2024/06/26
- [PATCH v2 20/21] qapi: convert "Example" sections with longer prose, John Snow, 2024/06/26
- [PATCH v2 16/21] docs/qapidoc: add QMP highlighting to annotated qmp-example blocks, John Snow, 2024/06/26
- [PATCH v2 21/21] qapi: remove "Example" doc section, John Snow, 2024/06/26