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.docutils import switch_source_input 28 from sphinx.util.nodes import nested_parse_with_titles 29 import sphinx 30 31 32 __version__ = '1.0' 33 34 # We parse hx files with a state machine which may be in one of two 35 # states: reading the C code fragment, or inside a rST fragment. 36 class HxState(Enum): 37 CTEXT = 1 38 RST = 2 39 40 def serror(file, lnum, errtext): 41 """Raise an exception giving a user-friendly syntax error message""" 42 raise ExtensionError('%s line %d: syntax error: %s' % (file, lnum, errtext)) 43 44 def parse_directive(line): 45 """Return first word of line, if any""" 46 return re.split(r'\W', line)[0] 47 48 def parse_defheading(file, lnum, line): 49 """Handle a DEFHEADING directive""" 50 # The input should be "DEFHEADING(some string)", though note that 51 # the 'some string' could be the empty string. If the string is 52 # empty we ignore the directive -- these are used only to add 53 # blank lines in the plain-text content of the --help output. 54 # 55 # Return the heading text. We strip out any trailing ':' for 56 # consistency with other headings in the rST documentation. 57 match = re.match(r'DEFHEADING\((.*?):?\)', line) 58 if match is None: 59 serror(file, lnum, "Invalid DEFHEADING line") 60 return match.group(1) 61 62 def parse_archheading(file, lnum, line): 63 """Handle an ARCHHEADING directive""" 64 # The input should be "ARCHHEADING(some string, other arg)", 65 # though note that the 'some string' could be the empty string. 66 # As with DEFHEADING, empty string ARCHHEADINGs will be ignored. 67 # 68 # Return the heading text. We strip out any trailing ':' for 69 # consistency with other headings in the rST documentation. 70 match = re.match(r'ARCHHEADING\((.*?):?,.*\)', line) 71 if match is None: 72 serror(file, lnum, "Invalid ARCHHEADING line") 73 return match.group(1) 74 75 def parse_srst(file, lnum, line): 76 """Handle an SRST directive""" 77 # The input should be either "SRST", or "SRST(label)". 78 match = re.match(r'SRST(\((.*?)\))?', line) 79 if match is None: 80 serror(file, lnum, "Invalid SRST line") 81 return match.group(2) 82 83 class HxtoolDocDirective(Directive): 84 """Extract rST fragments from the specified .hx file""" 85 required_argument = 1 86 optional_arguments = 1 87 option_spec = { 88 'hxfile': directives.unchanged_required 89 } 90 has_content = False 91 92 def run(self): 93 env = self.state.document.settings.env 94 hxfile = env.config.hxtool_srctree + '/' + self.arguments[0] 95 96 # Tell sphinx of the dependency 97 env.note_dependency(os.path.abspath(hxfile)) 98 99 state = HxState.CTEXT 100 # We build up lines of rST in this ViewList, which we will 101 # later put into a 'section' node. 102 rstlist = ViewList() 103 current_node = None 104 node_list = [] 105 106 with open(hxfile) as f: 107 lines = (l.rstrip() for l in f) 108 for lnum, line in enumerate(lines, 1): 109 directive = parse_directive(line) 110 111 if directive == 'HXCOMM': 112 pass 113 elif directive == 'SRST': 114 if state == HxState.RST: 115 serror(hxfile, lnum, 'expected ERST, found SRST') 116 else: 117 state = HxState.RST 118 label = parse_srst(hxfile, lnum, line) 119 if label: 120 rstlist.append("", hxfile, lnum - 1) 121 # Build label as _DOCNAME-HXNAME-LABEL 122 hx = os.path.splitext(os.path.basename(hxfile))[0] 123 refline = ".. _" + env.docname + "-" + hx + \ 124 "-" + label + ":" 125 rstlist.append(refline, hxfile, lnum - 1) 126 elif directive == 'ERST': 127 if state == HxState.CTEXT: 128 serror(hxfile, lnum, 'expected SRST, found ERST') 129 else: 130 state = HxState.CTEXT 131 elif directive == 'DEFHEADING' or directive == 'ARCHHEADING': 132 if directive == 'DEFHEADING': 133 heading = parse_defheading(hxfile, lnum, line) 134 else: 135 heading = parse_archheading(hxfile, lnum, line) 136 if heading == "": 137 continue 138 # Put the accumulated rST into the previous node, 139 # and then start a fresh section with this heading. 140 if len(rstlist) > 0: 141 if current_node is None: 142 # We had some rST fragments before the first 143 # DEFHEADING. We don't have a section to put 144 # these in, so rather than magicing up a section, 145 # make it a syntax error. 146 serror(hxfile, lnum, 147 'first DEFHEADING must precede all rST text') 148 self.do_parse(rstlist, current_node) 149 rstlist = ViewList() 150 if current_node is not None: 151 node_list.append(current_node) 152 section_id = 'hxtool-%d' % env.new_serialno('hxtool') 153 current_node = nodes.section(ids=[section_id]) 154 current_node += nodes.title(heading, heading) 155 else: 156 # Not a directive: put in output if we are in rST fragment 157 if state == HxState.RST: 158 # Sphinx counts its lines from 0 159 rstlist.append(line, hxfile, lnum - 1) 160 161 if current_node is None: 162 # We don't have multiple sections, so just parse the rst 163 # fragments into a dummy node so we can return the children. 164 current_node = nodes.section() 165 self.do_parse(rstlist, current_node) 166 return current_node.children 167 else: 168 # Put the remaining accumulated rST into the last section, and 169 # return all the sections. 170 if len(rstlist) > 0: 171 self.do_parse(rstlist, current_node) 172 node_list.append(current_node) 173 return node_list 174 175 # This is from kerneldoc.py -- it works around an API change in 176 # Sphinx between 1.6 and 1.7. Unlike kerneldoc.py, we use 177 # sphinx.util.nodes.nested_parse_with_titles() rather than the 178 # plain self.state.nested_parse(), and so we can drop the saving 179 # of title_styles and section_level that kerneldoc.py does, 180 # because nested_parse_with_titles() does that for us. 181 def do_parse(self, result, node): 182 with switch_source_input(self.state, result): 183 nested_parse_with_titles(self.state, result, node) 184 185 186 def setup(app): 187 """ Register hxtool-doc directive with Sphinx""" 188 app.add_config_value('hxtool_srctree', None, 'env') 189 app.add_directive('hxtool-doc', HxtoolDocDirective) 190 191 return dict( 192 version = __version__, 193 parallel_read_safe = True, 194 parallel_write_safe = True 195 ) 196