docs/ext/include_build_file.py

   1 import os
   2
   3 from docutils import nodes
   4 from docutils.parsers.rst import Directive
   5 from docutils.statemachine import StringList
   6 from sphinx.util.docutils import SphinxDirective
   7 from sphinx.util.nodes import nested_parse_with_titles
   8
   9 class IncludeBuildFile(SphinxDirective):
  10     """Add directive `include-build-file` to be used as follows:
  11
  12         .. include-build-file:: <filename>
  13
  14     The argument should be a filename of an rst files within one of the
  15     folders given by the `ibf_folders` config option.
  16     """
  17
  18     # The "arguments" are actually the content of the directive
  19     has_content = True
  20
  21     def run(self):
  22         filename = ''.join(self.content)
  23         for folder in self.env.config.ibf_folders:
  24             candidate = os.path.join(folder, filename)
  25             if os.path.isfile(candidate):
  26                 filename = candidate
  27                 break
  28         content = open(filename).readlines()
  29         content = [line.rstrip('\n') for line in content]
  30         # parse the string list
  31         node = nodes.Element()
  32         nested_parse_with_titles(self.state, StringList(content), node)
  33         self.state.document.settings.env.note_dependency(filename)
  34         return node.children
  35
  36
  37 def setup(app):
  38     app.add_config_value('ibf_folders', [], 'env')
  39     app.add_directive('include-build-file', IncludeBuildFile)
  40     return {
  41         'version': '0.1',
  42         'parallel_read_safe': True,
  43         'parallel_write_safe': True,
  44     }