Re: [PATCH v5 14/20] scripts/qapi: Remove texinfo generation support

[Markus Armbruster <armbru@redhat.com>]

Peter Maydell <peter.maydell@linaro.org> writes:

> We no longer use the generated texinfo format documentation,
> so delete the code that generates it, and the test case for
> the generation.
>
> Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>  Makefile                        |   1 -
>  scripts/qapi-gen.py             |   2 -
>  scripts/qapi/doc.py             | 302 ------------------------------
>  scripts/qapi/gen.py             |   7 -
>  tests/Makefile.include          |  15 +-
>  tests/qapi-schema/doc-good.texi | 313 --------------------------------
>  6 files changed, 1 insertion(+), 639 deletions(-)
>  delete mode 100644 scripts/qapi/doc.py
>  delete mode 100644 tests/qapi-schema/doc-good.texi
>
> diff --git a/Makefile b/Makefile
> index 3df1cf68333..fc3ccc15030 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -626,7 +626,6 @@ qemu-keymap$(EXESUF): QEMU_CFLAGS += $(XKBCOMMON_CFLAGS)
>  qapi-py = $(SRC_PATH)/scripts/qapi/__init__.py \
>  $(SRC_PATH)/scripts/qapi/commands.py \
>  $(SRC_PATH)/scripts/qapi/common.py \
> -$(SRC_PATH)/scripts/qapi/doc.py \
>  $(SRC_PATH)/scripts/qapi/error.py \
>  $(SRC_PATH)/scripts/qapi/events.py \
>  $(SRC_PATH)/scripts/qapi/expr.py \
> diff --git a/scripts/qapi-gen.py b/scripts/qapi-gen.py
> index 4b03f7d53be..541e8c1f55d 100755
> --- a/scripts/qapi-gen.py
> +++ b/scripts/qapi-gen.py
> @@ -10,7 +10,6 @@ import re
>  import sys
>  
>  from qapi.commands import gen_commands
> -from qapi.doc import gen_doc
>  from qapi.events import gen_events
>  from qapi.introspect import gen_introspect
>  from qapi.schema import QAPIError, QAPISchema
> @@ -51,7 +50,6 @@ def main(argv):
>      gen_commands(schema, args.output_dir, args.prefix)
>      gen_events(schema, args.output_dir, args.prefix)
>      gen_introspect(schema, args.output_dir, args.prefix, args.unmask)
> -    gen_doc(schema, args.output_dir, args.prefix)
>  
>  
>  if __name__ == '__main__':
> diff --git a/scripts/qapi/doc.py b/scripts/qapi/doc.py
> deleted file mode 100644
> index 7764de1e4bc..00000000000
> --- a/scripts/qapi/doc.py
> +++ /dev/null
[...]
> diff --git a/scripts/qapi/gen.py b/scripts/qapi/gen.py
> index bf5552a4e7f..ca66c82b5b8 100644
> --- a/scripts/qapi/gen.py
> +++ b/scripts/qapi/gen.py
> @@ -178,13 +178,6 @@ def ifcontext(ifcond, *args):
>          arg.end_if()
>  
>  
> -class QAPIGenDoc(QAPIGen):
> -
> -    def _top(self):
> -        return (super()._top()
> -                + '@c AUTOMATICALLY GENERATED, DO NOT MODIFY\n\n')
> -
> -
>  class QAPISchemaMonolithicCVisitor(QAPISchemaVisitor):
>  
>      def __init__(self, prefix, what, blurb, pydoc):
> diff --git a/tests/Makefile.include b/tests/Makefile.include
> index c7e4646ded7..ec83efeaa63 100644
> --- a/tests/Makefile.include
> +++ b/tests/Makefile.include
> @@ -38,7 +38,6 @@ export SRC_PATH
>  qapi-py = $(SRC_PATH)/scripts/qapi/__init__.py \
>  $(SRC_PATH)/scripts/qapi/commands.py \
>  $(SRC_PATH)/scripts/qapi/common.py \
> -$(SRC_PATH)/scripts/qapi/doc.py \
>  $(SRC_PATH)/scripts/qapi/error.py \
>  $(SRC_PATH)/scripts/qapi/events.py \
>  $(SRC_PATH)/scripts/qapi/expr.py \
> @@ -501,16 +500,8 @@ tests/test-qapi-gen-timestamp: \
>  	$(call quiet-command,$(PYTHON) $(SRC_PATH)/scripts/qapi-gen.py \
>  		-o tests -p "test-" $<, \
>  		"GEN","$(@:%-timestamp=%)")
> -	@rm -f tests/test-qapi-doc.texi
>  	@>$@
>  
> -tests/qapi-schema/doc-good.test.texi: $(SRC_PATH)/tests/qapi-schema/doc-good.json $(qapi-py)
> -	$(call quiet-command,$(PYTHON) $(SRC_PATH)/scripts/qapi-gen.py \
> -		-o tests/qapi-schema -p "doc-good-" $<, \
> -		"GEN","$@")
> -	@mv tests/qapi-schema/doc-good-qapi-doc.texi $@
> -	@rm -f tests/qapi-schema/doc-good-qapi-*.[ch] tests/qapi-schema/doc-good-qmp-*.[ch]
> -
>  tests/qtest/dbus-vmstate1.h tests/qtest/dbus-vmstate1.c: tests/qtest/dbus-vmstate1-gen-timestamp ;
>  tests/qtest/dbus-vmstate1-gen-timestamp: $(SRC_PATH)/tests/qtest/dbus-vmstate1.xml
>  	$(call quiet-command,$(GDBUS_CODEGEN) $< \
> @@ -891,10 +882,6 @@ check-tests/qapi-schema/frontend: $(addprefix $(SRC_PATH)/, $(check-qapi-schema-
>  	  PYTHONIOENCODING=utf-8 $(PYTHON) $(SRC_PATH)/tests/qapi-schema/test-qapi.py $^, \
>  	  TEST, check-qapi-schema)
>  
> -.PHONY: check-tests/qapi-schema/doc-good.texi
> -check-tests/qapi-schema/doc-good.texi: tests/qapi-schema/doc-good.test.texi
> -	@diff -u $(SRC_PATH)/tests/qapi-schema/doc-good.texi $<
> -

We shouldn't just delete this test.

It is for checking the doc generator does what it should for "good"
input.  "Bad" input is coverd by the other doc-*.json.

With the old doc generation system, the testing "good" input is
straightforward: generate Texinfo, diff to expected Texinfo, which is
committed to git.

This test has been invaliable when maintaining and extending doc.py.

With the new system, there is no ouput suitable for diffing, as the
various outputs all depend on the version of Sphinx.

Or is there?  Is there a way to have Sphinx "unparse" its internal
representation of the input?

If not, we should still run doc-good.json through the doc generator to
at least catch errors.  We still lose the ability to catch silent bad
output.

>  .PHONY: check-decodetree
>  check-decodetree:
>  	$(call quiet-command, \
> @@ -956,7 +943,7 @@ check-acceptance: check-venv $(TESTS_RESULTS_DIR) get-vm-images
>  # Consolidated targets
>  
>  .PHONY: check-block check-qapi-schema check-qtest check-unit check check-clean get-vm-images
> -check-qapi-schema: check-tests/qapi-schema/frontend check-tests/qapi-schema/doc-good.texi
> +check-qapi-schema: check-tests/qapi-schema/frontend
>  check-qtest: $(patsubst %,check-qtest-%, $(QTEST_TARGETS))
>  ifeq ($(CONFIG_TOOLS),y)
>  check-block: $(patsubst %,check-%, $(check-block-y))
> diff --git a/tests/qapi-schema/doc-good.texi b/tests/qapi-schema/doc-good.texi
> deleted file mode 100644
> index 12808989ffb..00000000000
> --- a/tests/qapi-schema/doc-good.texi
> +++ /dev/null
[...]