[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH 40/97] sphinx: add qmp_lexer
From: |
Michael Roth |
Subject: |
[PATCH 40/97] sphinx: add qmp_lexer |
Date: |
Tue, 1 Oct 2019 18:45:19 -0500 |
From: John Snow <address@hidden>
Sphinx, through Pygments, does not like annotated json examples very
much. In some versions of Sphinx (1.7), it will render the non-json
portions of code blocks in red, but in newer versions (2.0) it will
throw an exception and not highlight the block at all. Though we can
suppress this warning, it doesn't bring back highlighting on non-strict
json blocks.
We can alleviate this by creating a custom lexer for QMP examples that
allows us to properly highlight these examples in a robust way, keeping
our directionality and elision notations.
Signed-off-by: Eduardo Habkost <address@hidden>
Signed-off-by: John Snow <address@hidden>
Reported-by: Aarushi Mehta <address@hidden>
Reviewed-by: Peter Maydell <address@hidden>
Message-id: address@hidden
Signed-off-by: John Snow <address@hidden>
(cherry picked from commit cd231e13bdcb8d686b014bef940c7d19c6f1e769)
Signed-off-by: Michael Roth <address@hidden>
---
docs/conf.py | 4 ++--
docs/sphinx/qmp_lexer.py | 43 ++++++++++++++++++++++++++++++++++++++++
2 files changed, 45 insertions(+), 2 deletions(-)
create mode 100644 docs/sphinx/qmp_lexer.py
diff --git a/docs/conf.py b/docs/conf.py
index befbcc6c3e..e46b299b71 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -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']
diff --git a/docs/sphinx/qmp_lexer.py b/docs/sphinx/qmp_lexer.py
new file mode 100644
index 0000000000..f7e4c0e198
--- /dev/null
+++ b/docs/sphinx/qmp_lexer.py
@@ -0,0 +1,43 @@
+# QEMU Monitor Protocol Lexer Extension
+#
+# Copyright (C) 2019, Red Hat Inc.
+#
+# Authors:
+# Eduardo Habkost <address@hidden>
+# John Snow <address@hidden>
+#
+# 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())
--
2.17.1
- [PATCH 30/97] target/ppc: Fix lxvw4x, lxvh8x and lxvb16x, (continued)
- [PATCH 30/97] target/ppc: Fix lxvw4x, lxvh8x and lxvb16x, Michael Roth, 2019/10/01
- [PATCH 13/97] block/file-posix: Unaligned O_DIRECT block-status, Michael Roth, 2019/10/01
- [PATCH 29/97] target/ppc: Fix vsum2sws, Michael Roth, 2019/10/01
- [PATCH 34/97] target/i386: define md-clear bit, Michael Roth, 2019/10/01
- [PATCH 14/97] iotests: Test unaligned raw images with O_DIRECT, Michael Roth, 2019/10/01
- [PATCH 20/97] QEMUMachine: add events_wait method, Michael Roth, 2019/10/01
- [PATCH 33/97] target/i386: add MDS-NO feature, Michael Roth, 2019/10/01
- [PATCH 25/97] vhost: fix vhost_log size overflow during migration, Michael Roth, 2019/10/01
- [PATCH 02/97] qcow2: Add errp to preallocate_co(), Michael Roth, 2019/10/01
- [PATCH 37/97] usbredir: fix buffer-overflow on vmload, Michael Roth, 2019/10/01
- [PATCH 40/97] sphinx: add qmp_lexer,
Michael Roth <=
- [PATCH 31/97] q35: Revert to kernel irqchip, Michael Roth, 2019/10/01
- [PATCH 27/97] target/ppc: Fix xvxsigdp, Michael Roth, 2019/10/01
- [PATCH 26/97] target/ppc: Fix xvabs[sd]p, xvnabs[sd]p, xvneg[sd]p, xvcpsgn[sd]p, Michael Roth, 2019/10/01
- [PATCH 46/97] i386/acpi: show PCI Express bus on pxb-pcie expanders, Michael Roth, 2019/10/01
- [PATCH 56/97] tpm: Exit in reset when backend indicates failure, Michael Roth, 2019/10/01
- [PATCH 35/97] docs: recommend use of md-clear feature on all Intel CPUs, Michael Roth, 2019/10/01
- [PATCH 38/97] virtio-balloon: fix QEMU 4.0 config size migration incompatibility, Michael Roth, 2019/10/01
- [PATCH 49/97] virtio-balloon: Simplify deflate with pbp, Michael Roth, 2019/10/01
- [PATCH 44/97] hw/ssi/xilinx_spips: Avoid out-of-bound access to lqspi_buf[], Michael Roth, 2019/10/01
- [PATCH 51/97] virtio-balloon: Rework pbp tracking data, Michael Roth, 2019/10/01