docs/sphinx/qmp_lexer.py

   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
  13 from pygments.lexer import RegexLexer, DelegatingLexer
  14 from pygments.lexers.data import JsonLexer
  15 from pygments import token
  16 from sphinx import errors
  17
  18 class 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
  31 class 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
  37 def 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     )