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