summaryrefslogtreecommitdiffstats
path: root/third_party/waf/waflib/extras/sphinx.py
diff options
context:
space:
mode:
Diffstat (limited to 'third_party/waf/waflib/extras/sphinx.py')
-rw-r--r--third_party/waf/waflib/extras/sphinx.py120
1 files changed, 120 insertions, 0 deletions
diff --git a/third_party/waf/waflib/extras/sphinx.py b/third_party/waf/waflib/extras/sphinx.py
new file mode 100644
index 0000000..7d88f8a
--- /dev/null
+++ b/third_party/waf/waflib/extras/sphinx.py
@@ -0,0 +1,120 @@
+"""Support for Sphinx documentation
+
+This is a wrapper for sphinx-build program. Please note that sphinx-build supports only
+one output format at a time, but the tool can create multiple tasks to handle more.
+The output formats can be passed via the sphinx_output_format, which is an array of
+strings. For backwards compatibility if only one output is needed, it can be passed
+as a single string.
+The default output format is html.
+
+Specific formats can be installed in different directories by specifying the
+install_path_<FORMAT> attribute. If not defined, the standard install_path
+will be used instead.
+
+Example wscript:
+
+def configure(cnf):
+ conf.load('sphinx')
+
+def build(bld):
+ bld(
+ features='sphinx',
+ sphinx_source='sources', # path to source directory
+ sphinx_options='-a -v', # sphinx-build program additional options
+ sphinx_output_format=['html', 'man'], # output format of sphinx documentation
+ install_path_man='${DOCDIR}/man' # put man pages in a specific directory
+ )
+
+"""
+
+from waflib.Node import Node
+from waflib import Utils
+from waflib import Task
+from waflib.TaskGen import feature, after_method
+
+
+def configure(cnf):
+ """Check if sphinx-build program is available and loads gnu_dirs tool."""
+ cnf.find_program('sphinx-build', var='SPHINX_BUILD', mandatory=False)
+ cnf.load('gnu_dirs')
+
+
+@feature('sphinx')
+def build_sphinx(self):
+ """Builds sphinx sources.
+ """
+ if not self.env.SPHINX_BUILD:
+ self.bld.fatal('Program SPHINX_BUILD not defined.')
+ if not getattr(self, 'sphinx_source', None):
+ self.bld.fatal('Attribute sphinx_source not defined.')
+ if not isinstance(self.sphinx_source, Node):
+ self.sphinx_source = self.path.find_node(self.sphinx_source)
+ if not self.sphinx_source:
+ self.bld.fatal('Can\'t find sphinx_source: %r' % self.sphinx_source)
+
+ # In the taskgen we have the complete list of formats
+ Utils.def_attrs(self, sphinx_output_format='html')
+ self.sphinx_output_format = Utils.to_list(self.sphinx_output_format)
+
+ self.env.SPHINX_OPTIONS = getattr(self, 'sphinx_options', [])
+
+ for source_file in self.sphinx_source.ant_glob('**/*'):
+ self.bld.add_manual_dependency(self.sphinx_source, source_file)
+
+ for cfmt in self.sphinx_output_format:
+ sphinx_build_task = self.create_task('SphinxBuildingTask')
+ sphinx_build_task.set_inputs(self.sphinx_source)
+ # In task we keep the specific format this task is generating
+ sphinx_build_task.env.SPHINX_OUTPUT_FORMAT = cfmt
+
+ # the sphinx-build results are in <build + output_format> directory
+ sphinx_build_task.sphinx_output_directory = self.path.get_bld().make_node(cfmt)
+ sphinx_build_task.set_outputs(sphinx_build_task.sphinx_output_directory)
+ sphinx_build_task.sphinx_output_directory.mkdir()
+
+ Utils.def_attrs(sphinx_build_task, install_path=getattr(self, 'install_path_' + cfmt, getattr(self, 'install_path', get_install_path(sphinx_build_task))))
+
+
+def get_install_path(object):
+ if object.env.SPHINX_OUTPUT_FORMAT == 'man':
+ return object.env.MANDIR
+ elif object.env.SPHINX_OUTPUT_FORMAT == 'info':
+ return object.env.INFODIR
+ else:
+ return object.env.DOCDIR
+
+
+class SphinxBuildingTask(Task.Task):
+ color = 'BOLD'
+ run_str = '${SPHINX_BUILD} -M ${SPHINX_OUTPUT_FORMAT} ${SRC} ${TGT} ${SPHINX_OPTIONS}'
+
+ def keyword(self):
+ return 'Compiling (%s)' % self.env.SPHINX_OUTPUT_FORMAT
+
+ def runnable_status(self):
+
+ for x in self.run_after:
+ if not x.hasrun:
+ return Task.ASK_LATER
+
+ self.signature()
+ ret = Task.Task.runnable_status(self)
+ if ret == Task.SKIP_ME:
+ # in case the files were removed
+ self.add_install()
+ return ret
+
+
+ def post_run(self):
+ self.add_install()
+ return Task.Task.post_run(self)
+
+
+ def add_install(self):
+ nodes = self.sphinx_output_directory.ant_glob('**/*', quiet=True)
+ self.outputs += nodes
+ self.generator.add_install_files(install_to=self.install_path,
+ install_from=nodes,
+ postpone=False,
+ cwd=self.sphinx_output_directory.make_node(self.env.SPHINX_OUTPUT_FORMAT),
+ relative_trick=True)