Skip to content
Snippets Groups Projects
Select Git revision
  • feature/libtcg-rebase default protected
1 result
Search by author
  • Any Author
  • Anton Anton anjo
1 author
  1. Jan 05, 2022
  3. Dec 21, 2021
  5. Nov 08, 2021
  7. Aug 26, 2021
  9. Apr 30, 2021
  11. Apr 13, 2021
  13. Feb 15, 2021
  15. Dec 10, 2020
  17. Oct 17, 2020
  19. Oct 09, 2020
  21. Sep 29, 2020
    • Peter Maydell's avatar
      docs/sphinx: Add new qapi-doc Sphinx extension · 4078ee54
      Peter Maydell authored 
      
Some of our documentation is auto-generated from documentation
comments in the JSON schema.

For Sphinx, rather than creating a file to include, the most natural
way to handle this is to have a small custom Sphinx extension which
processes the JSON file and inserts documentation into the rST
file being processed.

This is the same approach that kerneldoc and hxtool use.

Signed-off-by: default avatarPeter Maydell <peter.maydell@linaro.org>
Message-Id: <20200925162316.21205-8-peter.maydell@linaro.org>
Reviewed-by: default avatarMarkus Armbruster <armbru@redhat.com>
[Comment and doc string formatting tweaked, unused method dropped,
a few line breaks tweaked to follow PEP 8 more closely, MAINTAINERS
section QAPI updated]
Signed-off-by: default avatarMarkus Armbruster <armbru@redhat.com>
      4078ee54
  23. Aug 21, 2020
  25. Apr 14, 2020
    • Peter Maydell's avatar
      kernel-doc: Use c:struct for Sphinx 3.0 and later · 152d1967
      Peter Maydell authored 
      
The kernel-doc Sphinx plugin and associated script currently emit
'c:type' directives for "struct foo" documentation.

Sphinx 3.0 warns about this:
  /home/petmay01/linaro/qemu-from-laptop/qemu/docs/../include/exec/memory.h:3: WARNING: Type must be either just a name or a typedef-like declaration.
  If just a name:
    Error in declarator or parameters
    Invalid C declaration: Expected identifier in nested name, got keyword: struct [error at 6]
      struct MemoryListener
      ------^
  If typedef-like declaration:
    Error in declarator or parameters
    Invalid C declaration: Expected identifier in nested name. [error at 21]
      struct MemoryListener
      ---------------------^

because it wants us to use the new-in-3.0 'c:struct' instead.

Plumb the Sphinx version through to the kernel-doc script
and use it to select 'c:struct' for newer versions than 3.0.

Fixes: LP:1872113
Signed-off-by: default avatarPeter Maydell <peter.maydell@linaro.org>
Reviewed-by: default avatarAlex Bennée <alex.bennee@linaro.org>
      152d1967
  27. Mar 12, 2020
  29. Mar 06, 2020
  31. Feb 03, 2020
    • Peter Maydell's avatar
      docs/sphinx: Add new hxtool Sphinx extension · 6803d6e9
      Peter Maydell authored 
      
Some of our documentation includes sections which are created
by assembling fragments of texinfo from a .hx source file into
a .texi file, which is then included from qemu-doc.texi or
qemu-img.texi.

For Sphinx, rather than creating a file to include, the most natural
way to handle this is to have a small custom Sphinx extension which
reads the .hx file and process it.  So instead of:
 * makefile produces foo.texi from foo.hx
 * qemu-doc.texi says '@include foo.texi'
we have:
 * qemu-doc.rst says 'hxtool-doc:: foo.hx'
 * the Sphinx extension for hxtool has code that runs to handle that
   Sphinx directive which reads the .hx file and emits the appropriate
   documentation contents

This is pretty much the same way the kerneldoc extension works right
now. It also has the advantage that it should work for third-party
services like readthedocs that expect to build the docs directly with
sphinx rather than by invoking our makefiles.

In this commit we implement the hxtool extension.

Note that syntax errors in the rST fragments will be correctly
reported to the user with the filename and line number within the
hx file.

Signed-off-by: default avatarPeter Maydell <peter.maydell@linaro.org>
Reviewed-by: default avatarAlex Bennée <alex.bennee@linaro.org>
Tested-by: default avatarAlex Bennée <alex.bennee@linaro.org>
Message-id: 20200124162606.8787-4-peter.maydell@linaro.org
      6803d6e9
  33. Dec 17, 2019
    • Paolo Bonzini's avatar
      docs: import Linux kernel-doc script and extension · e2c54635
      Paolo Bonzini authored 
      
Import Linux's kernel-doc script as of commit 15e2544ed38a1e, as well
as the Sphinx extension to call kernel-doc according to the arguments
and parameters given to a reStructuredText directive.

The kernel-doc extension accepts a filename, which is relative to
the QEMU source tree root.  The extension also notifies Sphinx about the
document dependency on the file, causing the document to be rebuilt when
the file has been changed.

Signed-off-by: default avatarPaolo Bonzini <pbonzini@redhat.com>
      e2c54635
  35. Jul 10, 2019