Documentation/sphinx/ir.py

   1 #!/usr/bin/env python
   2 # SPDX_License-Identifier: MIT
   3 #
   4 # Copyright (C) 2018 Luc Van Oostenryck <luc.vanoostenryck@gmail.com>
   5 #
   6
   7 """
   8 ///
   9 // To document the instructions used in the intermediate representation
  10 // a new domain is defined: 'ir' with a directive::
  11 //
  12 //      .. op: <OP_NAME>
  13 //              <description of OP_NAME>
  14 //              ...
  15 //
  16 // This is equivalent to using a definition list but with the name
  17 // also placed in the index (with 'IR instruction' as descriptions).
  18
  19 """
  20
  21 import docutils
  22 import sphinx
  23
  24 class IROpDirective(docutils.parsers.rst.Directive):
  25
  26         # use the first line of content as the argument, this allow
  27         # to not have to write a blanck line after the directive
  28         final_argument_whitespace = True
  29         required_argument = 0
  30         #optional_arguments = 0
  31         has_content = True
  32
  33         objtype = None
  34
  35         def run(self):
  36                 self.env = self.state.document.settings.env
  37
  38                 source = self.state.document
  39                 lineno = self.lineno
  40                 text = self.content
  41                 name = text[0]
  42
  43                 node = docutils.nodes.section()
  44                 node['ids'].append(name)
  45                 node.document = source
  46
  47                 index = '.. index:: pair: %s; IR instruction' % name
  48                 content = docutils.statemachine.ViewList()
  49                 content.append(index, source, lineno)
  50                 content.append(''   , source, lineno)
  51                 content.append(name , source, lineno)
  52                 content.append(''   , source, lineno)
  53                 self.state.nested_parse(content, self.content_offset, node)
  54
  55                 defnode = docutils.nodes.definition()
  56                 self.state.nested_parse(text[1:], self.content_offset, defnode)
  57                 node.append(defnode)
  58
  59                 return [node]
  60
  61 class IRDomain(sphinx.domains.Domain):
  62
  63     """IR domain."""
  64     name = 'ir'
  65
  66 def setup(app):
  67         app.add_domain(IRDomain)
  68         app.add_directive_to_domain('ir', 'op', IROpDirective)
  69
  70         return {
  71                 'version': '1.0',
  72                 'parallel_read_safe': True,
  73         }
  74
  75 # vim: tabstop=4