xref: /openbmc/qemu/docs/sphinx/qmp_lexer.py (revision ed8d9518)
1# QEMU Monitor Protocol Lexer Extension
2#
3# Copyright (C) 2019, Red Hat Inc.
4#
5# Authors:
6#  Eduardo Habkost <ehabkost@redhat.com>
7#  John Snow <jsnow@redhat.com>
8#
9# This work is licensed under the terms of the GNU GPLv2 or later.
10# See the COPYING file in the top-level directory.
11"""qmp_lexer is a Sphinx extension that provides a QMP lexer for code blocks."""
12
13from pygments.lexer import RegexLexer, DelegatingLexer
14from pygments.lexers.data import JsonLexer
15from pygments import token
16from sphinx import errors
17
18class QMPExampleMarkersLexer(RegexLexer):
19    """
20    QMPExampleMarkersLexer lexes QMP example annotations.
21    This lexer adds support for directionality flow and elision indicators.
22    """
23    tokens = {
24        'root': [
25            (r'-> ', token.Generic.Prompt),
26            (r'<- ', token.Generic.Prompt),
27            (r' ?\.{3} ?', token.Generic.Prompt),
28        ]
29    }
30
31class QMPExampleLexer(DelegatingLexer):
32    """QMPExampleLexer lexes annotated QMP examples."""
33    def __init__(self, **options):
34        super(QMPExampleLexer, self).__init__(JsonLexer, QMPExampleMarkersLexer,
35                                              token.Error, **options)
36
37def setup(sphinx):
38    """For use by the Sphinx extensions API."""
39    try:
40        sphinx.require_sphinx('2.1')
41        sphinx.add_lexer('QMP', QMPExampleLexer)
42    except errors.VersionRequirementError:
43        sphinx.add_lexer('QMP', QMPExampleLexer())
44
45    return dict(
46        parallel_read_safe = True,
47        parallel_write_safe = True
48    )
49