Teach sphinx a new ".. rootedliteralinclude::" directive.

It's like ".. literalinclude::" except the argument is an absolute path
which may contain environment variables to be be expanded when
generating documents.

doc/conf.py.in

@@ -41,7 +41,10 @@ btest_tests="doc/sphinx"
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions += ['bro', 'rst_directive', 'sphinx.ext.todo', 'adapt-toc']
+extensions += ['bro', 'rst_directive', 'sphinx.ext.todo', 'adapt-toc',
+               'rootedliteralinclude']
+
+os.environ["BRO_SRC_ROOT"] = "@CMAKE_SOURCE_DIR@"
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['sphinx-sources/_templates', 'sphinx-sources/_static']

doc/ext/rootedliteralinclude.py

@@ -0,0 +1,25 @@
+import os
+from sphinx.directives.code import LiteralInclude
+
+def setup(app):
+    app.add_directive('rootedliteralinclude', RootedLiteralInclude)
+
+class RootedLiteralInclude(LiteralInclude):
+    """
+    Like ``.. literalinclude::``, but the argument is an absolute path
+    which may contain environment variables which will be expanded when
+    generating documents.
+    """
+
+    def run(self):
+        document = self.state.document
+        if not document.settings.file_insertion_enabled:
+            return [document.reporter.warning('File insertion disabled',
+                                              line=self.lineno)]
+        env = document.settings.env
+
+        expanded_arg = os.path.expandvars(self.arguments[0])
+        sphinx_src_relation = os.path.relpath(expanded_arg, env.srcdir)
+        self.arguments[0] = os.path.join(os.sep, sphinx_src_relation)
+
+        return super(RootedLiteralInclude, self).run()