docs/sphinx/hxtool.py

1 # coding=utf-8
8 # See the COPYING file in the top-level directory.
9 """hxtool is a Sphinx extension that implements the hxtool-doc directive"""
11 # The purpose of this extension is to read fragments of rST
13 # The rST fragments are delimited by SRST/ERST lines.
14 # The conf.py file must set the hxtool_srctree config value to
16 # Each hxtool-doc:: directive takes one argument which is the
25 from docutils.parsers.rst import directives, Directive
35 # states: reading the C code fragment, or inside a rST fragment.
38     RST = 2  variable in HxState
41     """Raise an exception giving a user-friendly syntax error message"""
52     # empty we ignore the directive -- these are used only to add
53     # blank lines in the plain-text content of the --help output.
56     # consistency with other headings in the rST documentation.
69     # consistency with other headings in the rST documentation.
84     """Extract rST fragments from the specified .hx file"""
100         # We build up lines of rST in this ViewList, which we will
114                     if state == HxState.RST:
117                         state = HxState.RST
120                             rstlist.append("", hxfile, lnum - 1)
121                             # Build label as _DOCNAME-HXNAME-LABEL
123                             refline = ".. _" + env.docname + "-" + hx + \
124                                 "-" + label + ":"
125                             rstlist.append(refline, hxfile, lnum - 1)
138                     # Put the accumulated rST into the previous node,
142                             # We had some rST fragments before the first
147                                    'first DEFHEADING must precede all rST text')
152                     section_id = 'hxtool-%d' % env.new_serialno('hxtool')
156                     # Not a directive: put in output if we are in rST fragment
157                     if state == HxState.RST:
159                         rstlist.append(line, hxfile, lnum - 1)
162             # We don't have multiple sections, so just parse the rst
168             # Put the remaining accumulated rST into the last section, and
175     # This is from kerneldoc.py -- it works around an API change in
187     """ Register hxtool-doc directive with Sphinx"""
189     app.add_directive('hxtool-doc', HxtoolDocDirective)