From 01090cf09fe8d78e43a130fbf48a4184c12ee44b Mon Sep 17 00:00:00 2001 From: Jon Siwek Date: Wed, 9 Jan 2013 11:16:43 -0600 Subject: [PATCH] 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 | 5 ++++- doc/ext/rootedliteralinclude.py | 25 +++++++++++++++++++++++++ 2 files changed, 29 insertions(+), 1 deletion(-) create mode 100644 doc/ext/rootedliteralinclude.py diff --git a/doc/conf.py.in b/doc/conf.py.in index e91b48d079..8ca8d70a7a 100644 --- a/doc/conf.py.in +++ b/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'] diff --git a/doc/ext/rootedliteralinclude.py b/doc/ext/rootedliteralinclude.py new file mode 100644 index 0000000000..7b4aea5547 --- /dev/null +++ b/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()