docs/sphinx/hxtool.py

   1 # coding=utf-8
   2 #
   3 # QEMU hxtool .hx file parsing extension
   4 #
   5 # Copyright (c) 2020 Linaro
   6 #
   7 # This work is licensed under the terms of the GNU GPLv2 or later.
   8 # See the COPYING file in the top-level directory.
   9 """hxtool is a Sphinx extension that implements the hxtool-doc directive"""
  10
  11 # The purpose of this extension is to read fragments of rST
  12 # from .hx files, and insert them all into the current document.
  13 # The rST fragments are delimited by SRST/ERST lines.
  14 # The conf.py file must set the hxtool_srctree config value to
  15 # the root of the QEMU source tree.
  16 # Each hxtool-doc:: directive takes one argument which is the
  17 # path of the .hx file to process, relative to the source tree.
  18
  19 import os
  20 import re
  21 from enum import Enum
  22
  23 from docutils import nodes
  24 from docutils.statemachine import ViewList
  25 from docutils.parsers.rst import directives, Directive
  26 from sphinx.errors import ExtensionError
  27 from sphinx.util.nodes import nested_parse_with_titles
  28 import sphinx
  29
  30 # Sphinx up to 1.6 uses AutodocReporter; 1.7 and later
  31 # use switch_source_input. Check borrowed from kerneldoc.py.
  32 Use_SSI = sphinx.__version__[:3] >= '1.7'
  33 if Use_SSI:
  34     from sphinx.util.docutils import switch_source_input
  35 else:
  36     from sphinx.ext.autodoc import AutodocReporter
  37
  38 __version__ = '1.0'
  39
  40 # We parse hx files with a state machine which may be in one of three
  41 # states: reading the C code fragment, inside a texi fragment,
  42 # or inside a rST fragment.
  43 class HxState(Enum):
  44     CTEXT = 1
  45     TEXI = 2
  46     RST = 3
  47
  48 def serror(file, lnum, errtext):
  49     """Raise an exception giving a user-friendly syntax error message"""
  50     raise ExtensionError('%s line %d: syntax error: %s' % (file, lnum, errtext))
  51
  52 def parse_directive(line):
  53     """Return first word of line, if any"""
  54     return re.split('\W', line)[0]
  55
  56 def parse_defheading(file, lnum, line):
  57     """Handle a DEFHEADING directive"""
  58     # The input should be "DEFHEADING(some string)", though note that
  59     # the 'some string' could be the empty string. If the string is
  60     # empty we ignore the directive -- these are used only to add
  61     # blank lines in the plain-text content of the --help output.
  62     #
  63     # Return the heading text
  64     match = re.match(r'DEFHEADING\((.*)\)', line)
  65     if match is None:
  66         serror(file, lnum, "Invalid DEFHEADING line")
  67     return match.group(1)
  68
  69 def parse_archheading(file, lnum, line):
  70     """Handle an ARCHHEADING directive"""
  71     # The input should be "ARCHHEADING(some string, other arg)",
  72     # though note that the 'some string' could be the empty string.
  73     # As with DEFHEADING, empty string ARCHHEADINGs will be ignored.
  74     #
  75     # Return the heading text
  76     match = re.match(r'ARCHHEADING\((.*),.*\)', line)
  77     if match is None:
  78         serror(file, lnum, "Invalid ARCHHEADING line")
  79     return match.group(1)
  80
  81 class HxtoolDocDirective(Directive):
  82     """Extract rST fragments from the specified .hx file"""
  83     required_argument = 1
  84     optional_arguments = 1
  85     option_spec = {
  86         'hxfile': directives.unchanged_required
  87     }
  88     has_content = False
  89
  90     def run(self):
  91         env = self.state.document.settings.env
  92         hxfile = env.config.hxtool_srctree + '/' + self.arguments[0]
  93
  94         # Tell sphinx of the dependency
  95         env.note_dependency(os.path.abspath(hxfile))
  96
  97         state = HxState.CTEXT
  98         # We build up lines of rST in this ViewList, which we will
  99         # later put into a 'section' node.
 100         rstlist = ViewList()
 101         current_node = None
 102         node_list = []
 103
 104         with open(hxfile) as f:
 105             lines = (l.rstrip() for l in f)
 106             for lnum, line in enumerate(lines, 1):
 107                 directive = parse_directive(line)
 108
 109                 if directive == 'HXCOMM':
 110                     pass
 111                 elif directive == 'STEXI':
 112                     if state == HxState.RST:
 113                         serror(hxfile, lnum, 'expected ERST, found STEXI')
 114                     elif state == HxState.TEXI:
 115                         serror(hxfile, lnum, 'expected ETEXI, found STEXI')
 116                     else:
 117                         state = HxState.TEXI
 118                 elif directive == 'ETEXI':
 119                     if state == HxState.RST:
 120                         serror(hxfile, lnum, 'expected ERST, found ETEXI')
 121                     elif state == HxState.CTEXT:
 122                         serror(hxfile, lnum, 'expected STEXI, found ETEXI')
 123                     else:
 124                         state = HxState.CTEXT
 125                 elif directive == 'SRST':
 126                     if state == HxState.RST:
 127                         serror(hxfile, lnum, 'expected ERST, found SRST')
 128                     elif state == HxState.TEXI:
 129                         serror(hxfile, lnum, 'expected ETEXI, found SRST')
 130                     else:
 131                         state = HxState.RST
 132                 elif directive == 'ERST':
 133                     if state == HxState.TEXI:
 134                         serror(hxfile, lnum, 'expected ETEXI, found ERST')
 135                     elif state == HxState.CTEXT:
 136                         serror(hxfile, lnum, 'expected SRST, found ERST')
 137                     else:
 138                         state = HxState.CTEXT
 139                 elif directive == 'DEFHEADING' or directive == 'ARCHHEADING':
 140                     if directive == 'DEFHEADING':
 141                         heading = parse_defheading(hxfile, lnum, line)
 142                     else:
 143                         heading = parse_archheading(hxfile, lnum, line)
 144                     if heading == "":
 145                         continue
 146                     # Put the accumulated rST into the previous node,
 147                     # and then start a fresh section with this heading.
 148                     if len(rstlist) > 0:
 149                         if current_node is None:
 150                             # We had some rST fragments before the first
 151                             # DEFHEADING. We don't have a section to put
 152                             # these in, so rather than magicing up a section,
 153                             # make it a syntax error.
 154                             serror(hxfile, lnum,
 155                                    'first DEFHEADING must precede all rST text')
 156                         self.do_parse(rstlist, current_node)
 157                         rstlist = ViewList()
 158                     if current_node is not None:
 159                         node_list.append(current_node)
 160                     section_id = 'hxtool-%d' % env.new_serialno('hxtool')
 161                     current_node = nodes.section(ids=[section_id])
 162                     current_node += nodes.title(heading, heading)
 163                 else:
 164                     # Not a directive: put in output if we are in rST fragment
 165                     if state == HxState.RST:
 166                         # Sphinx counts its lines from 0
 167                         rstlist.append(line, hxfile, lnum - 1)
 168
 169         if current_node is None:
 170             # We don't have multiple sections, so just parse the rst
 171             # fragments into a dummy node so we can return the children.
 172             current_node = nodes.section()
 173             self.do_parse(rstlist, current_node)
 174             return current_node.children
 175         else:
 176             # Put the remaining accumulated rST into the last section, and
 177             # return all the sections.
 178             if len(rstlist) > 0:
 179                 self.do_parse(rstlist, current_node)
 180             node_list.append(current_node)
 181             return node_list
 182
 183     # This is from kerneldoc.py -- it works around an API change in
 184     # Sphinx between 1.6 and 1.7. Unlike kerneldoc.py, we use
 185     # sphinx.util.nodes.nested_parse_with_titles() rather than the
 186     # plain self.state.nested_parse(), and so we can drop the saving
 187     # of title_styles and section_level that kerneldoc.py does,
 188     # because nested_parse_with_titles() does that for us.
 189     def do_parse(self, result, node):
 190         if Use_SSI:
 191             with switch_source_input(self.state, result):
 192                 nested_parse_with_titles(self.state, result, node)
 193         else:
 194             save = self.state.memo.reporter
 195             self.state.memo.reporter = AutodocReporter(result, self.state.memo.reporter)
 196             try:
 197                 nested_parse_with_titles(self.state, result, node)
 198             finally:
 199                 self.state.memo.reporter = save
 200
 201 def setup(app):
 202     """ Register hxtool-doc directive with Sphinx"""
 203     app.add_config_value('hxtool_srctree', None, 'env')
 204     app.add_directive('hxtool-doc', HxtoolDocDirective)
 205
 206     return dict(
 207         version = __version__,
 208         parallel_read_safe = True,
 209         parallel_write_safe = True
 210     )