aboutsummaryrefslogtreecommitdiff
path: root/docs/sphinx
diff options
context:
space:
mode:
authorJohn Snow <jsnow@redhat.com>2019-07-10 15:08:06 -0400
committerJohn Snow <jsnow@redhat.com>2019-07-10 15:08:06 -0400
commitcd231e13bdcb8d686b014bef940c7d19c6f1e769 (patch)
tree80d259ae02f5cc7eb000a3623fc0e53dced536aa /docs/sphinx
parent575e6226287072bd0d6eb85d9712d280eb29c392 (diff)
downloadqemu-cd231e13bdcb8d686b014bef940c7d19c6f1e769.zip
qemu-cd231e13bdcb8d686b014bef940c7d19c6f1e769.tar.gz
qemu-cd231e13bdcb8d686b014bef940c7d19c6f1e769.tar.bz2
sphinx: add qmp_lexer
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 <ehabkost@redhat.com> Signed-off-by: John Snow <jsnow@redhat.com> Reported-by: Aarushi Mehta <mehta.aaru20@gmail.com> Reviewed-by: Peter Maydell <peter.maydell@linaro.org> Message-id: 20190603214653.29369-3-jsnow@redhat.com Signed-off-by: John Snow <jsnow@redhat.com>
Diffstat (limited to 'docs/sphinx')
-rw-r--r--docs/sphinx/qmp_lexer.py43
1 files changed, 43 insertions, 0 deletions
diff --git a/docs/sphinx/qmp_lexer.py b/docs/sphinx/qmp_lexer.py
new file mode 100644
index 0000000..f7e4c0e
--- /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 <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())