Add a qapi2texi script to generate the documentation from the qapi schemas.
The 15th patch in this series is a squashed version of the documentation move from qmp-commands.txt to the schemas. The whole version (not sent on the ML to avoid spamming) is in the following git branch: https://github.com/elmarco/qemu/commits/qapi-doc PDF preview: https://fedorapeople.org/~elmarco/qemu-qmp-ref.pdf v5: - many parser and generator fixes and improvements after v4 review: - simplified current section handling by using a Section object - adding a line is more stateful: either freeform or symbol comment - always check_docs() when parsing with QAPISchema - simplified some code and comments - do not break current section on empty line, but break after a non indented paragraph in an argument section. This seems to reflects the way documentation is written: ## # @foo: # @arg: fluctuat nec mergitur # - continues here # # Since: 1853 # # Body # ## Other sections (Note/Examples etc) are not indented (it seems), but could use a similar rule. I prefer to keep this only for args, for styling reasons (bikeshedding?). - better handling of flat-union in generator - list all enum values (even when not documented) - added qapi-doc parsing tests and more error checking - pep8/pylint fixes - some more schema doc fixes - do not move logo to docs/ v4: - more device_add schema fixes - do not merge docs/qmp-intro.txt in qemu-qmp-ref.texi - remove needless @ifinfo, add GPL copying text - added qemu logo to pdf - added some r-b tags v3: - many improvements to the doc parser: - throws an error in various malformated conditions - allows multiple meta-sections, except for "Since:" and "Return:" - build a list of docs, instead of attaching docs to expressions - accept() breaks on new doc block, and get_doc() returns a QAPIDoc - fix more documentation to fit the new parser - use a master texi file that includes the generated file, instead of templated texi file - texi fixes after Markus review - only build and install html and man pages by default - fix .gitignore v2: - change licence to be lgpl2+ - fix some comments & commit message - add more code comments - improve the doc parsing to treat only "Since" as a special case not requiring ":" (common notation in the doc) - include some early schema doc fixes (to fix generated doc) - include the squashed version of the doc move - include the man page and installation build changes Marc-André Lureau (17): qapi: improve device_add schema qga/schema: fix double-return in doc qga/schema: improve guest-set-vcpus Returns: section qapi: fix schema symbol sections qapi: fix missing symbol @prefix qapi: fix various symbols mismatch in documentation qapi: use one symbol per line qapi: add missing colon-ending for section name qapi: add some sections in docs qapi: improve TransactionAction doc docs: add master qapi texi files qapi: rename QAPIExprError/QAPILineError qapi: add qapi2texi script texi2pod: learn quotation, deftp and deftypefn (SQUASHED) move doc to schema docs: add qemu logo build-sys: add qapi doc generation targets Makefile | 57 +- tests/Makefile.include | 17 + scripts/qapi.py | 361 ++- scripts/qapi2texi.py | 331 +++ scripts/texi2pod.pl | 53 +- .gitignore | 11 +- docs/qapi-code-gen.txt | 54 +- docs/qemu-ga-ref.texi | 82 + docs/qemu-qmp-ref.texi | 82 + docs/qemu_logo.pdf | Bin 0 -> 9117 bytes docs/qmp-commands.txt | 3824 -------------------------- docs/qmp-events.txt | 731 ----- docs/qmp-intro.txt | 3 +- qapi-schema.json | 1662 +++++++++-- qapi/block-core.json | 894 +++++- qapi/block.json | 82 +- qapi/common.json | 52 +- qapi/crypto.json | 41 +- qapi/event.json | 304 +- qapi/introspect.json | 28 +- qapi/rocker.json | 63 +- qapi/trace.json | 25 +- qga/qapi-schema.json | 64 +- tests/qapi-schema/doc-bad-args.err | 1 + tests/qapi-schema/doc-bad-args.exit | 1 + tests/qapi-schema/doc-bad-args.json | 6 + tests/qapi-schema/doc-bad-args.out | 0 tests/qapi-schema/doc-bad-symbol.err | 1 + tests/qapi-schema/doc-bad-symbol.exit | 1 + tests/qapi-schema/doc-bad-symbol.json | 4 + tests/qapi-schema/doc-bad-symbol.out | 0 tests/qapi-schema/doc-duplicated-arg.err | 1 + tests/qapi-schema/doc-duplicated-arg.exit | 1 + tests/qapi-schema/doc-duplicated-arg.json | 5 + tests/qapi-schema/doc-duplicated-arg.out | 0 tests/qapi-schema/doc-duplicated-return.err | 1 + tests/qapi-schema/doc-duplicated-return.exit | 1 + tests/qapi-schema/doc-duplicated-return.json | 6 + tests/qapi-schema/doc-duplicated-return.out | 0 tests/qapi-schema/doc-duplicated-since.err | 1 + tests/qapi-schema/doc-duplicated-since.exit | 1 + tests/qapi-schema/doc-duplicated-since.json | 6 + tests/qapi-schema/doc-duplicated-since.out | 0 tests/qapi-schema/doc-empty-arg.err | 1 + tests/qapi-schema/doc-empty-arg.exit | 1 + tests/qapi-schema/doc-empty-arg.json | 4 + tests/qapi-schema/doc-empty-arg.out | 0 tests/qapi-schema/doc-empty-section.err | 1 + tests/qapi-schema/doc-empty-section.exit | 1 + tests/qapi-schema/doc-empty-section.json | 6 + tests/qapi-schema/doc-empty-section.out | 0 tests/qapi-schema/doc-empty-symbol.err | 1 + tests/qapi-schema/doc-empty-symbol.exit | 1 + tests/qapi-schema/doc-empty-symbol.json | 3 + tests/qapi-schema/doc-empty-symbol.out | 0 tests/qapi-schema/doc-invalid-end.err | 1 + tests/qapi-schema/doc-invalid-end.exit | 1 + tests/qapi-schema/doc-invalid-end.json | 3 + tests/qapi-schema/doc-invalid-end.out | 0 tests/qapi-schema/doc-invalid-end2.err | 1 + tests/qapi-schema/doc-invalid-end2.exit | 1 + tests/qapi-schema/doc-invalid-end2.json | 3 + tests/qapi-schema/doc-invalid-end2.out | 0 tests/qapi-schema/doc-invalid-return.err | 1 + tests/qapi-schema/doc-invalid-return.exit | 1 + tests/qapi-schema/doc-invalid-return.json | 5 + tests/qapi-schema/doc-invalid-return.out | 0 tests/qapi-schema/doc-invalid-section.err | 1 + tests/qapi-schema/doc-invalid-section.exit | 1 + tests/qapi-schema/doc-invalid-section.json | 4 + tests/qapi-schema/doc-invalid-section.out | 0 tests/qapi-schema/doc-invalid-start.err | 1 + tests/qapi-schema/doc-invalid-start.exit | 1 + tests/qapi-schema/doc-invalid-start.json | 3 + tests/qapi-schema/doc-invalid-start.out | 0 tests/qapi-schema/doc-missing-expr.err | 1 + tests/qapi-schema/doc-missing-expr.exit | 1 + tests/qapi-schema/doc-missing-expr.json | 3 + tests/qapi-schema/doc-missing-expr.out | 0 tests/qapi-schema/doc-missing-space.err | 1 + tests/qapi-schema/doc-missing-space.exit | 1 + tests/qapi-schema/doc-missing-space.json | 4 + tests/qapi-schema/doc-missing-space.out | 0 tests/qapi-schema/qapi-schema-test.json | 58 + tests/qapi-schema/qapi-schema-test.out | 49 + tests/qapi-schema/test-qapi.py | 12 + 86 files changed, 3922 insertions(+), 5113 deletions(-) create mode 100755 scripts/qapi2texi.py create mode 100644 docs/qemu-ga-ref.texi create mode 100644 docs/qemu-qmp-ref.texi create mode 100644 docs/qemu_logo.pdf delete mode 100644 docs/qmp-commands.txt delete mode 100644 docs/qmp-events.txt create mode 100644 tests/qapi-schema/doc-bad-args.err create mode 100644 tests/qapi-schema/doc-bad-args.exit create mode 100644 tests/qapi-schema/doc-bad-args.json create mode 100644 tests/qapi-schema/doc-bad-args.out create mode 100644 tests/qapi-schema/doc-bad-symbol.err create mode 100644 tests/qapi-schema/doc-bad-symbol.exit create mode 100644 tests/qapi-schema/doc-bad-symbol.json create mode 100644 tests/qapi-schema/doc-bad-symbol.out create mode 100644 tests/qapi-schema/doc-duplicated-arg.err create mode 100644 tests/qapi-schema/doc-duplicated-arg.exit create mode 100644 tests/qapi-schema/doc-duplicated-arg.json create mode 100644 tests/qapi-schema/doc-duplicated-arg.out create mode 100644 tests/qapi-schema/doc-duplicated-return.err create mode 100644 tests/qapi-schema/doc-duplicated-return.exit create mode 100644 tests/qapi-schema/doc-duplicated-return.json create mode 100644 tests/qapi-schema/doc-duplicated-return.out create mode 100644 tests/qapi-schema/doc-duplicated-since.err create mode 100644 tests/qapi-schema/doc-duplicated-since.exit create mode 100644 tests/qapi-schema/doc-duplicated-since.json create mode 100644 tests/qapi-schema/doc-duplicated-since.out create mode 100644 tests/qapi-schema/doc-empty-arg.err create mode 100644 tests/qapi-schema/doc-empty-arg.exit create mode 100644 tests/qapi-schema/doc-empty-arg.json create mode 100644 tests/qapi-schema/doc-empty-arg.out create mode 100644 tests/qapi-schema/doc-empty-section.err create mode 100644 tests/qapi-schema/doc-empty-section.exit create mode 100644 tests/qapi-schema/doc-empty-section.json create mode 100644 tests/qapi-schema/doc-empty-section.out create mode 100644 tests/qapi-schema/doc-empty-symbol.err create mode 100644 tests/qapi-schema/doc-empty-symbol.exit create mode 100644 tests/qapi-schema/doc-empty-symbol.json create mode 100644 tests/qapi-schema/doc-empty-symbol.out create mode 100644 tests/qapi-schema/doc-invalid-end.err create mode 100644 tests/qapi-schema/doc-invalid-end.exit create mode 100644 tests/qapi-schema/doc-invalid-end.json create mode 100644 tests/qapi-schema/doc-invalid-end.out create mode 100644 tests/qapi-schema/doc-invalid-end2.err create mode 100644 tests/qapi-schema/doc-invalid-end2.exit create mode 100644 tests/qapi-schema/doc-invalid-end2.json create mode 100644 tests/qapi-schema/doc-invalid-end2.out create mode 100644 tests/qapi-schema/doc-invalid-return.err create mode 100644 tests/qapi-schema/doc-invalid-return.exit create mode 100644 tests/qapi-schema/doc-invalid-return.json create mode 100644 tests/qapi-schema/doc-invalid-return.out create mode 100644 tests/qapi-schema/doc-invalid-section.err create mode 100644 tests/qapi-schema/doc-invalid-section.exit create mode 100644 tests/qapi-schema/doc-invalid-section.json create mode 100644 tests/qapi-schema/doc-invalid-section.out create mode 100644 tests/qapi-schema/doc-invalid-start.err create mode 100644 tests/qapi-schema/doc-invalid-start.exit create mode 100644 tests/qapi-schema/doc-invalid-start.json create mode 100644 tests/qapi-schema/doc-invalid-start.out create mode 100644 tests/qapi-schema/doc-missing-expr.err create mode 100644 tests/qapi-schema/doc-missing-expr.exit create mode 100644 tests/qapi-schema/doc-missing-expr.json create mode 100644 tests/qapi-schema/doc-missing-expr.out create mode 100644 tests/qapi-schema/doc-missing-space.err create mode 100644 tests/qapi-schema/doc-missing-space.exit create mode 100644 tests/qapi-schema/doc-missing-space.json create mode 100644 tests/qapi-schema/doc-missing-space.out -- 2.10.0
