diff options
| author | Luc Van Oostenryck <luc.vanoostenryck@gmail.com> | 2018-05-20 16:55:23 +0200 |
|---|---|---|
| committer | Luc Van Oostenryck <luc.vanoostenryck@gmail.com> | 2018-05-21 03:50:16 +0200 |
| commit | f477cb74ff136db72e810819283a957b44275fb8 (patch) | |
| tree | d74a170f7e6fd30516020d8f2da5fed7350c9d6e /Documentation/sphinx | |
| parent | 9a6bc349fa1f3f9bd39a242dbef74609038c8946 (diff) | |
| download | sparse-dev-f477cb74ff136db72e810819283a957b44275fb8.tar.gz | |
doc: add sphinx domain for IR instruction indexation
The doc for IR instructions used definition lists to structure
the instructions names and their description. This is simple
to write and present well but it doesn't put the instructions'
name in the index.
Fix this by adding a new domain, with a single directive 'op'
which takes the instruction name, inserts an index entry and uses
it for the definition.
Signed-off-by: Luc Van Oostenryck <luc.vanoostenryck@gmail.com>
Diffstat (limited to 'Documentation/sphinx')
| -rwxr-xr-x | Documentation/sphinx/ir.py | 75 |
1 files changed, 75 insertions, 0 deletions
diff --git a/Documentation/sphinx/ir.py b/Documentation/sphinx/ir.py new file mode 100755 index 00000000..3028200a --- /dev/null +++ b/Documentation/sphinx/ir.py @@ -0,0 +1,75 @@ +#!/usr/bin/env python +# SPDX_License-Identifier: MIT +# +# Copyright (C) 2018 Luc Van Oostenryck <luc.vanoostenryck@gmail.com> +# + +""" +/// +// To document the instructions used in the intermediate representation +// a new domain is defined: 'ir' with a directive:: +// +// .. op: <OP_NAME> +// <description of OP_NAME> +// ... +// +// This is equivalent to using a definition list but with the name +// also placed in the index (with 'IR instruction' as descriptions). + +""" + +import docutils +import sphinx + +class IROpDirective(docutils.parsers.rst.Directive): + + # use the first line of content as the argument, this allow + # to not have to write a blanck line after the directive + final_argument_whitespace = True + required_argument = 0 + #optional_arguments = 0 + has_content = True + + objtype = None + + def run(self): + self.env = self.state.document.settings.env + + source = self.state.document + lineno = self.lineno + text = self.content + name = text[0] + + node = docutils.nodes.section() + node['ids'].append(name) + node.document = source + + index = '.. index:: pair: %s; IR instruction' % name + content = docutils.statemachine.ViewList() + content.append(index, source, lineno) + content.append('' , source, lineno) + content.append(name , source, lineno) + content.append('' , source, lineno) + self.state.nested_parse(content, self.content_offset, node) + + defnode = docutils.nodes.definition() + self.state.nested_parse(text[1:], self.content_offset, defnode) + node.append(defnode) + + return [node] + +class IRDomain(sphinx.domains.Domain): + + """IR domain.""" + name = 'ir' + +def setup(app): + app.add_domain(IRDomain) + app.add_directive_to_domain('ir', 'op', IROpDirective) + + return { + 'version': '1.0', + 'parallel_read_safe': True, + } + +# vim: tabstop=4 |