Pull request
-----BEGIN PGP SIGNATURE----- iQIzBAABCAAdFiEE+ber27ys35W+dsvQfe+BBqr8OQ4FAl0mOtYACgkQfe+BBqr8 OQ6ExBAAu8SRJA7/+crHNLrpemSTuD8IWhqyBET1hNN2F7E73kGq4YcZt5xMiH8W kgrytVslc4JZfXdbTKADEDDaNV/24HUOeGQjo7MwrzrouuFbFoxp1I89xi3hLQbZ w4rwnhUfbqc41wH4WlHan+gt5oD27S4Lvd410OEn2tv5pKE8eb4NIt7Jwsbtqa5C 1/yMWIry7PIbUPPAP/ghYniCg8dyKXttSTaWnKfdo/BR+NbJcNJ3wa53KoZxlXuT U/DN6PBnCE4WAL3y8a2wyTv2upDXz4/bKlbqqTHE6zz6XkgfJl2I2+UwbMQzlEAN dmmp7JHikoxpW+go6VT2ihMOTdGP00yvgwRuHHYGQwFJkoApZC9t8SDg0D3tBJcs rYFcs/5dlq96pLXIhIECs8zVe0plqFbEaXpg8RhRmtr9m2Eafir8u8J9OKCCXXAQ PAot+7UNR/aXLFwVCjfq5A/lwvxfnVUj8V61aCu6GaCH8RSthXyHLY8IoVZ+r6Cb IVFmTiy1tcwakT6Wg0CuDfdU07sxdnSqzJJqhGjKpFyayiQxjxdeujI2mYSZcSLT ZPANZybTVnZzGZsnFCB7wjiJAkAOuj34isISP2Dn4eaCTBqrcF19imNLJD0ey1SX gUWD9U6bcPeUDI+iVdHmZ5bmabomgXiBt/ELgwPxRWxS8qrdYXY= =xLgo -----END PGP SIGNATURE----- Merge remote-tracking branch 'remotes/jnsnow/tags/bitmaps-pull-request' into staging Pull request # gpg: Signature made Wed 10 Jul 2019 20:21:58 BST # gpg: using RSA key F9B7ABDBBCACDF95BE76CBD07DEF8106AAFC390E # gpg: Good signature from "John Snow (John Huston) <jsnow@redhat.com>" [full] # Primary key fingerprint: FAEB 9711 A12C F475 812F 18F2 88A9 064D 1835 61EB # Subkey fingerprint: F9B7 ABDB BCAC DF95 BE76 CBD0 7DEF 8106 AAFC 390E * remotes/jnsnow/tags/bitmaps-pull-request: docs/bitmaps: use QMP lexer instead of json sphinx: add qmp_lexer docs/interop/bitmaps.rst: Fix typos Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
This commit is contained in:
Peter Maydell
commit
9411db8f37
|
|
@ -41,7 +41,7 @@ except NameError:
|
|||
# add these directories to sys.path here. If the directory is relative to the
|
||||
# documentation root, use an absolute path starting from qemu_docdir.
|
||||
#
|
||||
# sys.path.insert(0, os.path.join(qemu_docdir, "my_subdir"))
|
||||
sys.path.insert(0, os.path.join(qemu_docdir, "sphinx"))
|
||||
|
||||
|
||||
# -- General configuration ------------------------------------------------
|
||||
|
|
@ -54,7 +54,7 @@ needs_sphinx = '1.3'
|
|||
# Add any Sphinx extension module names here, as strings. They can be
|
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||
# ones.
|
||||
extensions = []
|
||||
extensions = ['qmp_lexer']
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ['_templates']
|
||||
|
|
|
|||
|
|
@ -199,7 +199,7 @@ persistence, and recording state can be adjusted at creation time.
|
|||
|
||||
to create a new, actively recording persistent bitmap:
|
||||
|
||||
.. code:: json
|
||||
.. code-block:: QMP
|
||||
|
||||
-> { "execute": "block-dirty-bitmap-add",
|
||||
"arguments": {
|
||||
|
|
@ -220,7 +220,7 @@ persistence, and recording state can be adjusted at creation time.
|
|||
To create a new, disabled (``-recording``), transient bitmap that tracks
|
||||
changes in 32KiB segments:
|
||||
|
||||
.. code:: json
|
||||
.. code-block:: QMP
|
||||
|
||||
-> { "execute": "block-dirty-bitmap-add",
|
||||
"arguments": {
|
||||
|
|
@ -254,7 +254,7 @@ Deletes a bitmap. Bitmaps that are ``+busy`` cannot be removed.
|
|||
|
||||
Remove a bitmap named ``bitmap0`` from node ``drive0``:
|
||||
|
||||
.. code:: json
|
||||
.. code-block:: QMP
|
||||
|
||||
-> { "execute": "block-dirty-bitmap-remove",
|
||||
"arguments": {
|
||||
|
|
@ -280,7 +280,7 @@ Clears all dirty bits from a bitmap. ``+busy`` bitmaps cannot be cleared.
|
|||
|
||||
Clear all dirty bits from bitmap ``bitmap0`` on node ``drive0``:
|
||||
|
||||
.. code:: json
|
||||
.. code-block:: QMP
|
||||
|
||||
-> { "execute": "block-dirty-bitmap-clear",
|
||||
"arguments": {
|
||||
|
|
@ -309,7 +309,7 @@ begin being recorded. ``+busy`` bitmaps cannot be enabled.
|
|||
|
||||
To set ``+recording`` on bitmap ``bitmap0`` on node ``drive0``:
|
||||
|
||||
.. code:: json
|
||||
.. code-block:: QMP
|
||||
|
||||
-> { "execute": "block-dirty-bitmap-enable",
|
||||
"arguments": {
|
||||
|
|
@ -347,7 +347,7 @@ writes to begin being ignored. ``+busy`` bitmaps cannot be disabled.
|
|||
|
||||
To set ``-recording`` on bitmap ``bitmap0`` on node ``drive0``:
|
||||
|
||||
.. code:: json
|
||||
.. code-block:: QMP
|
||||
|
||||
-> { "execute": "block-dirty-bitmap-disable",
|
||||
"arguments": {
|
||||
|
|
@ -393,13 +393,13 @@ in any one source bitmap, the target bitmap will mark that segment dirty.
|
|||
``drive0``. If ``new_bitmap`` was empty prior to this command, this achieves
|
||||
a copy.
|
||||
|
||||
.. code:: json
|
||||
.. code-block:: QMP
|
||||
|
||||
-> { "execute": "block-dirty-bitmap-merge",
|
||||
"arguments": {
|
||||
"node": "drive0",
|
||||
"target": "new_bitmap",
|
||||
"bitmaps: [ "bitmap0" ]
|
||||
"bitmaps": [ "bitmap0" ]
|
||||
}
|
||||
}
|
||||
|
||||
|
|
@ -424,7 +424,7 @@ attached to nodes serving as the root for guest devices.
|
|||
API. This result highlights a bitmap ``bitmap0`` attached to the root node of
|
||||
device ``drive0``.
|
||||
|
||||
.. code:: json
|
||||
.. code-block:: QMP
|
||||
|
||||
-> {
|
||||
"execute": "query-block",
|
||||
|
|
@ -562,7 +562,7 @@ new, empty bitmap that records writes from this point in time forward.
|
|||
destination. These writes will be recorded in the bitmap
|
||||
accordingly.
|
||||
|
||||
.. code:: json
|
||||
.. code-block:: QMP
|
||||
|
||||
-> {
|
||||
"execute": "transaction",
|
||||
|
|
@ -650,7 +650,7 @@ Example: Resetting an Incremental Backup Anchor Point
|
|||
If we want to start a new backup chain with an existing bitmap, we can also
|
||||
use a transaction to reset the bitmap while making a new full backup:
|
||||
|
||||
.. code:: json
|
||||
.. code-block:: QMP
|
||||
|
||||
-> {
|
||||
"execute": "transaction",
|
||||
|
|
@ -730,7 +730,7 @@ Example: First Incremental Backup
|
|||
|
||||
#. Issue an incremental backup command:
|
||||
|
||||
.. code:: json
|
||||
.. code-block:: QMP
|
||||
|
||||
-> {
|
||||
"execute": "drive-backup",
|
||||
|
|
@ -788,7 +788,7 @@ Example: Second Incremental Backup
|
|||
#. Issue a new incremental backup command. The only difference here is that we
|
||||
have changed the target image below.
|
||||
|
||||
.. code:: json
|
||||
.. code-block:: QMP
|
||||
|
||||
-> {
|
||||
"execute": "drive-backup",
|
||||
|
|
@ -869,7 +869,7 @@ image:
|
|||
#. Issue a new incremental backup command. Apart from the new destination
|
||||
image, there is no difference from the last two examples.
|
||||
|
||||
.. code:: json
|
||||
.. code-block:: QMP
|
||||
|
||||
-> {
|
||||
"execute": "drive-backup",
|
||||
|
|
@ -932,7 +932,7 @@ point in time.
|
|||
|
||||
#. Create a full (anchor) backup for each drive, with accompanying bitmaps:
|
||||
|
||||
.. code:: json
|
||||
.. code-block:: QMP
|
||||
|
||||
-> {
|
||||
"execute": "transaction",
|
||||
|
|
@ -1018,7 +1018,7 @@ point in time.
|
|||
|
||||
#. Issue a multi-drive incremental push backup transaction:
|
||||
|
||||
.. code:: json
|
||||
.. code-block:: QMP
|
||||
|
||||
-> {
|
||||
"execute": "transaction",
|
||||
|
|
@ -1121,7 +1121,7 @@ described above. This example demonstrates the single-job failure case:
|
|||
|
||||
#. Attempt to create an incremental backup via QMP:
|
||||
|
||||
.. code:: json
|
||||
.. code-block:: QMP
|
||||
|
||||
-> {
|
||||
"execute": "drive-backup",
|
||||
|
|
@ -1139,7 +1139,7 @@ described above. This example demonstrates the single-job failure case:
|
|||
|
||||
#. Receive a pair of events indicating failure:
|
||||
|
||||
.. code:: json
|
||||
.. code-block:: QMP
|
||||
|
||||
<- {
|
||||
"timestamp": {...},
|
||||
|
|
@ -1175,7 +1175,7 @@ described above. This example demonstrates the single-job failure case:
|
|||
#. Retry the command after fixing the underlying problem, such as
|
||||
freeing up space on the backup volume:
|
||||
|
||||
.. code:: json
|
||||
.. code-block:: QMP
|
||||
|
||||
-> {
|
||||
"execute": "drive-backup",
|
||||
|
|
@ -1193,7 +1193,7 @@ described above. This example demonstrates the single-job failure case:
|
|||
|
||||
#. Receive confirmation that the job completed successfully:
|
||||
|
||||
.. code:: json
|
||||
.. code-block:: QMP
|
||||
|
||||
<- {
|
||||
"timestamp": {...},
|
||||
|
|
@ -1233,7 +1233,7 @@ and one succeeds:
|
|||
|
||||
#. Issue the transaction to start a backup of both drives.
|
||||
|
||||
.. code:: json
|
||||
.. code-block:: QMP
|
||||
|
||||
-> {
|
||||
"execute": "transaction",
|
||||
|
|
@ -1267,13 +1267,13 @@ and one succeeds:
|
|||
#. Receive notice that the Transaction was accepted, and jobs were
|
||||
launched:
|
||||
|
||||
.. code:: json
|
||||
.. code-block:: QMP
|
||||
|
||||
<- { "return": {} }
|
||||
|
||||
#. Receive notice that the first job has completed:
|
||||
|
||||
.. code:: json
|
||||
.. code-block:: QMP
|
||||
|
||||
<- {
|
||||
"timestamp": {...},
|
||||
|
|
@ -1289,7 +1289,7 @@ and one succeeds:
|
|||
|
||||
#. Receive notice that the second job has failed:
|
||||
|
||||
.. code:: json
|
||||
.. code-block:: QMP
|
||||
|
||||
<- {
|
||||
"timestamp": {...},
|
||||
|
|
@ -1365,7 +1365,7 @@ applied:
|
|||
|
||||
#. Issue the multi-drive incremental backup transaction:
|
||||
|
||||
.. code:: json
|
||||
.. code-block:: QMP
|
||||
|
||||
-> {
|
||||
"execute": "transaction",
|
||||
|
|
@ -1401,13 +1401,13 @@ applied:
|
|||
|
||||
#. Receive notice that the Transaction was accepted, and jobs were launched:
|
||||
|
||||
.. code:: json
|
||||
.. code-block:: QMP
|
||||
|
||||
<- { "return": {} }
|
||||
|
||||
#. Receive notification that the backup job for ``drive1`` has failed:
|
||||
|
||||
.. code:: json
|
||||
.. code-block:: QMP
|
||||
|
||||
<- {
|
||||
"timestamp": {...},
|
||||
|
|
@ -1434,10 +1434,10 @@ applied:
|
|||
|
||||
#. Receive notification that the job for ``drive0`` has been cancelled:
|
||||
|
||||
.. code:: json
|
||||
.. code-block:: QMP
|
||||
|
||||
<- {
|
||||
"timestamp": {...}
|
||||
"timestamp": {...},
|
||||
"data": {
|
||||
"device": "drive0",
|
||||
"type": "backup",
|
||||
|
|
|
|||
|
|
@ -0,0 +1,43 @@
|
|||
# QEMU Monitor Protocol Lexer Extension
|
||||
#
|
||||
# Copyright (C) 2019, Red Hat Inc.
|
||||
#
|
||||
# Authors:
|
||||
# Eduardo Habkost <ehabkost@redhat.com>
|
||||
# John Snow <jsnow@redhat.com>
|
||||
#
|
||||
# This work is licensed under the terms of the GNU GPLv2 or later.
|
||||
# See the COPYING file in the top-level directory.
|
||||
"""qmp_lexer is a Sphinx extension that provides a QMP lexer for code blocks."""
|
||||
|
||||
from pygments.lexer import RegexLexer, DelegatingLexer
|
||||
from pygments.lexers.data import JsonLexer
|
||||
from pygments import token
|
||||
from sphinx import errors
|
||||
|
||||
class QMPExampleMarkersLexer(RegexLexer):
|
||||
"""
|
||||
QMPExampleMarkersLexer lexes QMP example annotations.
|
||||
This lexer adds support for directionality flow and elision indicators.
|
||||
"""
|
||||
tokens = {
|
||||
'root': [
|
||||
(r'-> ', token.Generic.Prompt),
|
||||
(r'<- ', token.Generic.Prompt),
|
||||
(r' ?\.{3} ?', token.Generic.Prompt),
|
||||
]
|
||||
}
|
||||
|
||||
class QMPExampleLexer(DelegatingLexer):
|
||||
"""QMPExampleLexer lexes annotated QMP examples."""
|
||||
def __init__(self, **options):
|
||||
super(QMPExampleLexer, self).__init__(JsonLexer, QMPExampleMarkersLexer,
|
||||
token.Error, **options)
|
||||
|
||||
def setup(sphinx):
|
||||
"""For use by the Sphinx extensions API."""
|
||||
try:
|
||||
sphinx.require_sphinx('2.1')
|
||||
sphinx.add_lexer('QMP', QMPExampleLexer)
|
||||
except errors.VersionRequirementError:
|
||||
sphinx.add_lexer('QMP', QMPExampleLexer())
|
||||
Loading…
Reference in New Issue