1"""Support for Sphinx documentation
2
3This is a wrapper for sphinx-build program. Please note that sphinx-build supports only one output format which can
4passed to build via sphinx_output_format attribute. The default output format is html.
5
6Example wscript:
7
8def configure(cnf):
9    conf.load('sphinx')
10
11def build(bld):
12    bld(
13        features='sphinx',
14        sphinx_source='sources',  # path to source directory
15        sphinx_options='-a -v',  # sphinx-build program additional options
16        sphinx_output_format='man'  # output format of sphinx documentation
17        )
18
19"""
20
21from waflib.Node import Node
22from waflib import Utils
23from waflib.Task import Task
24from waflib.TaskGen import feature, after_method
25
26
27def configure(cnf):
28    """Check if sphinx-build program is available and loads gnu_dirs tool."""
29    cnf.find_program('sphinx-build', var='SPHINX_BUILD', mandatory=False)
30    cnf.load('gnu_dirs')
31
32
33@feature('sphinx')
34def build_sphinx(self):
35    """Builds sphinx sources.
36    """
37    if not self.env.SPHINX_BUILD:
38        self.bld.fatal('Program SPHINX_BUILD not defined.')
39    if not getattr(self, 'sphinx_source', None):
40        self.bld.fatal('Attribute sphinx_source not defined.')
41    if not isinstance(self.sphinx_source, Node):
42        self.sphinx_source = self.path.find_node(self.sphinx_source)
43    if not self.sphinx_source:
44        self.bld.fatal('Can\'t find sphinx_source: %r' % self.sphinx_source)
45
46    Utils.def_attrs(self, sphinx_output_format='html')
47    self.env.SPHINX_OUTPUT_FORMAT = self.sphinx_output_format
48    self.env.SPHINX_OPTIONS = getattr(self, 'sphinx_options', [])
49
50    for source_file in self.sphinx_source.ant_glob('**/*'):
51        self.bld.add_manual_dependency(self.sphinx_source, source_file)
52
53    sphinx_build_task = self.create_task('SphinxBuildingTask')
54    sphinx_build_task.set_inputs(self.sphinx_source)
55    sphinx_build_task.set_outputs(self.path.get_bld())
56
57    # the sphinx-build results are in <build + output_format> directory
58    sphinx_output_directory = self.path.get_bld().make_node(self.env.SPHINX_OUTPUT_FORMAT)
59    sphinx_output_directory.mkdir()
60    Utils.def_attrs(self, install_path=get_install_path(self))
61    self.add_install_files(install_to=self.install_path,
62                           install_from=sphinx_output_directory.ant_glob('**/*'),
63                           cwd=sphinx_output_directory,
64                           relative_trick=True)
65
66
67def get_install_path(tg):
68    if tg.env.SPHINX_OUTPUT_FORMAT == 'man':
69        return tg.env.MANDIR
70    elif tg.env.SPHINX_OUTPUT_FORMAT == 'info':
71        return tg.env.INFODIR
72    else:
73        return tg.env.DOCDIR
74
75
76class SphinxBuildingTask(Task):
77    color = 'BOLD'
78    run_str = '${SPHINX_BUILD} -M ${SPHINX_OUTPUT_FORMAT} ${SRC} ${TGT} ${SPHINX_OPTIONS}'
79
80    def keyword(self):
81        return 'Compiling (%s)' % self.env.SPHINX_OUTPUT_FORMAT
82