Skip to content

Q
qemu

openeuler / qemu

通知 10
Star 0
Fork 0
Q
qemu

体验新版 GitCode，发现更多精彩内容 >>

切换分支/标签
  1. 19 2月, 2020 8 次提交
  3. 17 2月, 2020 17 次提交
  5. 15 2月, 2020 15 次提交
    • P
      qapi: Delete all the "foo: dropped in n.n" notes · bb5ccf22
      由 Peter Maydell 提交于 
      A handful of QAPI doc comments include lines like
"ppcemb: dropped in 3.1". The doc comment parser will just
put these into whatever the preceding section was; sometimes
that's "Notes", and sometimes it's some random other section,
as with "NetClientDriver" where the "'dump': dropped in 2.12"
line ends up in the "Since:" section.

This tends to render wrongly, more so in the upcoming rST
generator, but sometimes even in the Texinfo, as in the case
of QKeyCode:
   ac_bookmarks
       since 2.10 altgr, altgr_r: dropped in 2.10

Since commit 3264ffce (v4.2.0), we have a better place to tell
users about deprecated and deleted functionality --
qemu-deprecated.texi.  These "dropped in" remarks all predate it, and
other feature drops of that vintage are not documented anywhere, so
moving these to qemu-deprecated.texi makes little sense.  Drop them
instead.
Signed-off-by: NPeter Maydell <peter.maydell@linaro.org>
Message-Id: <20200213175647.17628-19-peter.maydell@linaro.org>
Reviewed-by: NMarkus Armbruster <armbru@redhat.com>
[Commit message tweaked]
Signed-off-by: NMarkus Armbruster <armbru@redhat.com>
      bb5ccf22
    • P
      qapi/migration.json: Replace _this_ with *this* · a660eed4
      由 Peter Maydell 提交于 
      The MigrationInfo::setup-time documentation is the only place where we
use _this_ inline markup for emphasis, commonly rendered in italics.
We would like to switch the doc comments to rST format, but rST
doesn't recognize that markup and emits literal underscores.

Switch to *this* instead.  Changes markup to strong emphasis with
Texinfo, commonly rendered as bold.  With rST, it will go right back
to emphasis / italics.

rST also uses **this** for strong (commonly rendered bold) where
Texinfo uses *this*. We have one place in the doc comments
which uses strong/bold markup, in qapi/introspect.json:
    Note: the QAPI schema is also used to help define *internal*

When we switch to rST that will be rendered as emphasis / italics.
Markus (who wrote that) thinks that using emphasis / italics
there is an improvement, so we leave that markup alone.
Signed-off-by: NPeter Maydell <peter.maydell@linaro.org>
Reviewed-by: NMarkus Armbruster <armbru@redhat.com>
Message-Id: <20200213175647.17628-18-peter.maydell@linaro.org>
Reviewed-by: NPhilippe Mathieu-Daudé <philmd@redhat.com>
[Commit message tweaked]
Signed-off-by: NMarkus Armbruster <armbru@redhat.com>
      a660eed4
    • P
      qapi: Add blank lines before bulleted lists · 100cc4fe
      由 Peter Maydell 提交于 
      We would like to switch the doc comments to rST format. rST
insists on a blank line before and after a bulleted list, but our
Texinfo doc generator did not. Add some extra blank lines in the doc
comments so they're acceptable rST input.
Signed-off-by: NPeter Maydell <peter.maydell@linaro.org>
Reviewed-by: NPhilippe Mathieu-Daudé <philmd@redhat.com>
Message-Id: <20200213175647.17628-17-peter.maydell@linaro.org>
Reviewed-by: NMarkus Armbruster <armbru@redhat.com>
[Commit message tweaked]
Signed-off-by: NMarkus Armbruster <armbru@redhat.com>
      100cc4fe
    • P
      qapi: Use explicit bulleted lists · e050e426
      由 Peter Maydell 提交于 
      A JSON block comment like this:
     Returns: nothing on success
              If @node is not a valid block device, DeviceNotFound
              If @name is not found, GenericError with an explanation

renders like this:

     Returns: nothing on success If node is not a valid block device,
     DeviceNotFound If name is not found, GenericError with an explanation

because whitespace is not significant.

Use an actual bulleted list, so that the formatting is correct.
Signed-off-by: NPeter Maydell <peter.maydell@linaro.org>
Message-Id: <20200213175647.17628-14-peter.maydell@linaro.org>
Message-Id: <20200213175647.17628-15-peter.maydell@linaro.org>
Message-Id: <20200213175647.17628-16-peter.maydell@linaro.org>
[Three commits squashed into one]
Reviewed-by: NMarkus Armbruster <armbru@redhat.com>
Signed-off-by: NMarkus Armbruster <armbru@redhat.com>
      e050e426
    • P
      qapi/ui.json: Avoid `...' Texinfo style quoting · 449be9df
      由 Peter Maydell 提交于 
      Avoid Texinfo style quoting with `...', because we would like to
switch the doc comments to rST format, and rST treats it as a syntax
error. Use '...' instead, as we do in other doc comments. This looks
OK in Texinfo, and rST formats it as paired-quotation-marks.
Signed-off-by: NPeter Maydell <peter.maydell@linaro.org>
Reviewed-by: NMarkus Armbruster <armbru@redhat.com>
Message-Id: <20200213175647.17628-13-peter.maydell@linaro.org>
[Commit message tweaked]
Signed-off-by: NMarkus Armbruster <armbru@redhat.com>
      449be9df
    • P
      qapi/ui.json: Put input-send-event body text in the right place · 43d7c2d0
      由 Peter Maydell 提交于 
      In the doc comment for input-send-event, there is a multi-line
chunk of text ("The @device...take precedence") which is intended
to be the main body text describing the event. However it has
been placed after the arguments and Returns: section, which
means that the parser actually thinks that this text is
part of the "Returns" section text.

Move the body text up to the top so that the parser correctly
classifies it as body.
Signed-off-by: NPeter Maydell <peter.maydell@linaro.org>
Reviewed-by: NMarkus Armbruster <armbru@redhat.com>
Message-Id: <20200213175647.17628-12-peter.maydell@linaro.org>
Signed-off-by: NMarkus Armbruster <armbru@redhat.com>
      43d7c2d0
    • P
      qapi: Remove hardcoded tabs · dbb28bc8
      由 Peter Maydell 提交于 
      There are some stray hardcoded tabs in some of our json files;
remove them.
Signed-off-by: NPeter Maydell <peter.maydell@linaro.org>
Reviewed-by: NMarkus Armbruster <armbru@redhat.com>
Message-Id: <20200213175647.17628-11-peter.maydell@linaro.org>
Signed-off-by: NMarkus Armbruster <armbru@redhat.com>
      dbb28bc8
    • P
      qapi: Fix indent level on doc comments in json files · 26ec4e53
      由 Peter Maydell 提交于 
      The current doc generation doesn't care much about indentation levels,
but we would like to switch to an rST format, and rST does care about
indentation.

Make the doc comments more strongly consistent about indentation
for multiline constructs like:

@arg: description line 1
      description line 2

Returns: line one
         line 2

so that there is always exactly one space after the colon, and
subsequent lines align with the first.

This commit is a purely whitespace change, and it does not alter the
generated .texi files (because the texi generation code strips away
all the extra whitespace).  This does mean that we end up with some
over-length lines.

Note that when the documentation for an argument fits on a single
line like this:

@arg: one line only

then stray extra spaces after the ':' don't affect the rST output, so
I have not attempted to methodically fix them, though the preference
is a single space here too.
Signed-off-by: NPeter Maydell <peter.maydell@linaro.org>
Message-Id: <20200213175647.17628-10-peter.maydell@linaro.org>
Reviewed-by: NMarkus Armbruster <armbru@redhat.com>
[Commit message tweaked]
Signed-off-by: NMarkus Armbruster <armbru@redhat.com>
      26ec4e53
    • P
      qapi: Fix incorrect "Not documented" claims in QMP documentation · f5627506
      由 Peter Maydell 提交于 
      Some qapi doc comments have forgotten the ':' after the
@argument, like this:

# @filename         Filename for the new image file
# @size             Size of the virtual disk in bytes

The result is that these are parsed as part of the body
text and appear as a run-on line:
  filename Filename for the new image file size Size of the virtual disk in bytes"
followed by
  filename: string
    Not documented
  size: int
    Not documented

in the 'Members' section.

Correct the formatting.
Signed-off-by: NPeter Maydell <peter.maydell@linaro.org>
Reviewed-by: NMarkus Armbruster <armbru@redhat.com>
Message-Id: <20200213175647.17628-9-peter.maydell@linaro.org>
[Commit message tweaked]
Signed-off-by: NMarkus Armbruster <armbru@redhat.com>
      f5627506
    • P
      qapi/block-core.json: Use literal block for ascii art · 0a940d66
      由 Peter Maydell 提交于 
      The ascii-art graph in the BlockLatencyHistogramInfo documentation
doesn't render correctly, because the whitespace is collapsed.

Use the '|' format that emits a literal 'example' block so the graph
is displayed correctly.

Strictly the Texinfo generated is still wrong because each line
goes into its own @example environment, but it renders better
than what we had before.

Fixing this rendering is a necessary prerequisite for the upcoming rST
generator, which otherwise complains about the inconsistent
indentation in the ascii-art graph.
Signed-off-by: NPeter Maydell <peter.maydell@linaro.org>
Message-Id: <20200213175647.17628-8-peter.maydell@linaro.org>
Reviewed-by: NMarkus Armbruster <armbru@redhat.com>
[Commit message tweaked]
Signed-off-by: NMarkus Armbruster <armbru@redhat.com>
      0a940d66
    • P
      qga/qapi-schema.json: minor format fixups for rST · a7b6e896
      由 Peter Maydell 提交于 
      We would like to switch the doc comments to rST format, and rST
requires a blank line before the start of a bulleted or enumerated
list. Two places in qapi-schema.json were missing this blank line.

Some places were using an indented line as a sort of single-item
bulleted list, which in the Texinfo output comes out all run
onto a single line; use a real bulleted list instead.

Some places unnecessarily indented lists, which confuses rST.

guest-fstrim:minimum's documentation was indented the
right amount to share a line with @minimum, but wasn't
actually doing so.

The indent on the bulleted list in the guest-set-vcpus
Returns section meant rST misindented it.

Changes to the generated Texinfo are very minor (the new
bulleted lists, and a few extra blank lines).
Signed-off-by: NPeter Maydell <peter.maydell@linaro.org>
Message-Id: <20200213175647.17628-7-peter.maydell@linaro.org>
[Commit message tweaked]
Signed-off-by: NMarkus Armbruster <armbru@redhat.com>
      a7b6e896
    • P
      qga/qapi-schema.json: Fix indent level on doc comments · 883aff68
      由 Peter Maydell 提交于 
      The current doc generation doesn't care much about indentation levels,
but we would like to switch to an rST format, and rST does care about
indentation.

Make the doc comments more strongly consistent about indentation
for multiline constructs like:

@arg: description line 1
      description line 2

Returns: line one
         line 2

so that there is always exactly one space after the colon, and
subsequent lines align with the first.

This commit is a purely whitespace change, and it does not alter the
generated .texi files (because the texi generation code strips away
all the extra whitespace).  This does mean that we end up with some
over-length lines.

Note that when the documentation for an argument fits on a single
line like this:

@arg: one line only

then stray extra spaces after the ':' don't affect the rST output, so
I have not attempted to methodically fix them, though the preference
is a single space here too.
Signed-off-by: NPeter Maydell <peter.maydell@linaro.org>
Reviewed-by: NMarkus Armbruster <armbru@redhat.com>
Message-Id: <20200213175647.17628-6-peter.maydell@linaro.org>
[Commit message tweaked]
Signed-off-by: NMarkus Armbruster <armbru@redhat.com>
      883aff68
    • P
      qga/qapi-schema.json: Fix missing '-' in GuestDiskBusType doc comment · 72ec8bf3
      由 Peter Maydell 提交于 
      The doc comment for GuestDiskBusType doesn't match up with the
enumeration because of a missing hyphen in 'file-backed-virtual'.
This means the docs are rendered wrongly:
       "virtual"
           Win virtual bus type "file-backed" virtual: Win file-backed bus type

       "file-backed-virtual"
           Not documented

Add the missing hyphen.
Signed-off-by: NPeter Maydell <peter.maydell@linaro.org>
Reviewed-by: NEric Blake <eblake@redhat.com>
Reviewed-by: NMarkus Armbruster <armbru@redhat.com>
Message-Id: <20200213175647.17628-5-peter.maydell@linaro.org>
Signed-off-by: NMarkus Armbruster <armbru@redhat.com>
      72ec8bf3
    • P
      Makefile: Fix typo in dependency list for interop manpages · 18064a62
      由 Peter Maydell 提交于 
      Fix a typo in the dependency list for the manpages built from the
'interop' manual, which meant we were accidentally not including
the .hx file in the dependency list.

Fixes: e13c59faSigned-off-by: NPeter Maydell <peter.maydell@linaro.org>
Reviewed-by: NPhilippe Mathieu-Daudé <philmd@redhat.com>
Message-Id: <20200213175647.17628-4-peter.maydell@linaro.org>
Signed-off-by: NMarkus Armbruster <armbru@redhat.com>
      18064a62
    • P
      configure: Check that sphinx-build is using Python 3 · 758b617a
      由 Peter Maydell 提交于 
      Currently configure's has_sphinx_build() check simply runs a dummy
sphinx-build and either passes or fails.  This means that "no
sphinx-build at all" and "sphinx-build exists but is too old" are
both reported the same way.

Further, we want to assume that all the Python we write is running
with at least Python 3.5; configure checks that for our scripts, but
Sphinx extensions run with whatever Python version sphinx-build
itself is using.

Add a check to our conf.py which makes sphinx-build fail if it would
be running our extensions with an old Python, and handle this
in configure so we can report failure helpfully to the user.
This will mean that configure --enable-docs will fail like this
if the sphinx-build provided is not suitable:

Warning: sphinx-build exists but it is either too old or uses too old a Python version

ERROR: User requested feature docs
       configure was not able to find it.
       Install texinfo, Perl/perl-podlators and a Python 3 version of python-sphinx

(As usual, the default is to simply not build the docs, as we would
if sphinx-build wasn't present at all.)
Signed-off-by: NPeter Maydell <peter.maydell@linaro.org>
Reviewed-by: NAlex Bennée <alex.bennee@linaro.org>
Reviewed-by: NWainer dos Santos Moschetta <wainersm@redhat.com>
Message-Id: <20200213175647.17628-3-peter.maydell@linaro.org>
Signed-off-by: NMarkus Armbruster <armbru@redhat.com>
      758b617a