linux-user: Add support for btrfs ioctls used to manage quota
[qemu.git] / 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 two
41 # states: reading the C code fragment, or inside a rST fragment.
42 class HxState(Enum):
43 CTEXT = 1
44 RST = 2
45
46 def serror(file, lnum, errtext):
47 """Raise an exception giving a user-friendly syntax error message"""
48 raise ExtensionError('%s line %d: syntax error: %s' % (file, lnum, errtext))
49
50 def parse_directive(line):
51 """Return first word of line, if any"""
52 return re.split('\W', line)[0]
53
54 def parse_defheading(file, lnum, line):
55 """Handle a DEFHEADING directive"""
56 # The input should be "DEFHEADING(some string)", though note that
57 # the 'some string' could be the empty string. If the string is
58 # empty we ignore the directive -- these are used only to add
59 # blank lines in the plain-text content of the --help output.
60 #
61 # Return the heading text. We strip out any trailing ':' for
62 # consistency with other headings in the rST documentation.
63 match = re.match(r'DEFHEADING\((.*?):?\)', line)
64 if match is None:
65 serror(file, lnum, "Invalid DEFHEADING line")
66 return match.group(1)
67
68 def parse_archheading(file, lnum, line):
69 """Handle an ARCHHEADING directive"""
70 # The input should be "ARCHHEADING(some string, other arg)",
71 # though note that the 'some string' could be the empty string.
72 # As with DEFHEADING, empty string ARCHHEADINGs will be ignored.
73 #
74 # Return the heading text. We strip out any trailing ':' for
75 # consistency with other headings in the rST documentation.
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 == 'SRST':
112 if state == HxState.RST:
113 serror(hxfile, lnum, 'expected ERST, found SRST')
114 else:
115 state = HxState.RST
116 elif directive == 'ERST':
117 if state == HxState.CTEXT:
118 serror(hxfile, lnum, 'expected SRST, found ERST')
119 else:
120 state = HxState.CTEXT
121 elif directive == 'DEFHEADING' or directive == 'ARCHHEADING':
122 if directive == 'DEFHEADING':
123 heading = parse_defheading(hxfile, lnum, line)
124 else:
125 heading = parse_archheading(hxfile, lnum, line)
126 if heading == "":
127 continue
128 # Put the accumulated rST into the previous node,
129 # and then start a fresh section with this heading.
130 if len(rstlist) > 0:
131 if current_node is None:
132 # We had some rST fragments before the first
133 # DEFHEADING. We don't have a section to put
134 # these in, so rather than magicing up a section,
135 # make it a syntax error.
136 serror(hxfile, lnum,
137 'first DEFHEADING must precede all rST text')
138 self.do_parse(rstlist, current_node)
139 rstlist = ViewList()
140 if current_node is not None:
141 node_list.append(current_node)
142 section_id = 'hxtool-%d' % env.new_serialno('hxtool')
143 current_node = nodes.section(ids=[section_id])
144 current_node += nodes.title(heading, heading)
145 else:
146 # Not a directive: put in output if we are in rST fragment
147 if state == HxState.RST:
148 # Sphinx counts its lines from 0
149 rstlist.append(line, hxfile, lnum - 1)
150
151 if current_node is None:
152 # We don't have multiple sections, so just parse the rst
153 # fragments into a dummy node so we can return the children.
154 current_node = nodes.section()
155 self.do_parse(rstlist, current_node)
156 return current_node.children
157 else:
158 # Put the remaining accumulated rST into the last section, and
159 # return all the sections.
160 if len(rstlist) > 0:
161 self.do_parse(rstlist, current_node)
162 node_list.append(current_node)
163 return node_list
164
165 # This is from kerneldoc.py -- it works around an API change in
166 # Sphinx between 1.6 and 1.7. Unlike kerneldoc.py, we use
167 # sphinx.util.nodes.nested_parse_with_titles() rather than the
168 # plain self.state.nested_parse(), and so we can drop the saving
169 # of title_styles and section_level that kerneldoc.py does,
170 # because nested_parse_with_titles() does that for us.
171 def do_parse(self, result, node):
172 if Use_SSI:
173 with switch_source_input(self.state, result):
174 nested_parse_with_titles(self.state, result, node)
175 else:
176 save = self.state.memo.reporter
177 self.state.memo.reporter = AutodocReporter(result, self.state.memo.reporter)
178 try:
179 nested_parse_with_titles(self.state, result, node)
180 finally:
181 self.state.memo.reporter = save
182
183 def setup(app):
184 """ Register hxtool-doc directive with Sphinx"""
185 app.add_config_value('hxtool_srctree', None, 'env')
186 app.add_directive('hxtool-doc', HxtoolDocDirective)
187
188 return dict(
189 version = __version__,
190 parallel_read_safe = True,
191 parallel_write_safe = True
192 )