qemu/docs/sphinx/qmp_lexer.py
John Snow cd231e13bd 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>
2019-07-10 15:08:06 -04:00

44 lines
1.4 KiB
Python

# 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())