[Qemu-devel] [PATCH v5 00/17] qapi doc generation (whole version, squashed)

[Marc-André Lureau]

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