build: update sphinx tool

Use the improved version from the ndn-cxx repository

Refs: #5298
Change-Id: I27c9f97757e3b4d8c6cbfc3ff191ecee4cfa067f

.waf-tools/boost.py

@@ -1,6 +1,3 @@
-#!/usr/bin/env python
-# encoding: utf-8
-#
 # partially based on boost.py written by Gernot Vormayr
 # written by Ruediger Sonderfeld <[email protected]>, 2008
 # modified by Bjoern Michaelsen, 2008

.waf-tools/coverage.py

@@ -1,5 +1,3 @@
-# -*- Mode: python; py-indent-offset: 4; indent-tabs-mode: nil; coding: utf-8; -*-
-
 from waflib import TaskGen
 
 def options(opt):

.waf-tools/default-compiler-flags.py

@@ -1,5 +1,3 @@
-# -*- Mode: python; py-indent-offset: 4; indent-tabs-mode: nil; coding: utf-8; -*-
-
 import platform
 from waflib import Configure, Logs, Utils
 
@@ -128,16 +126,16 @@ def getCompilerVersion(self, conf):
 
     def getGeneralFlags(self, conf):
         """Get dict of CXXFLAGS, LINKFLAGS, and DEFINES that are always needed"""
+        return {'CXXFLAGS': [], 'LINKFLAGS': [], 'DEFINES': []}
+
+    def getDebugFlags(self, conf):
+        """Get dict of CXXFLAGS, LINKFLAGS, and DEFINES that are needed only in debug mode"""
         return {
             'CXXFLAGS': [],
             'LINKFLAGS': [],
             'DEFINES': ['BOOST_ASIO_NO_DEPRECATED', 'BOOST_FILESYSTEM_NO_DEPRECATED'],
         }
 
-    def getDebugFlags(self, conf):
-        """Get dict of CXXFLAGS, LINKFLAGS, and DEFINES that are needed only in debug mode"""
-        return {'CXXFLAGS': [], 'LINKFLAGS': [], 'DEFINES': []}
-
     def getOptimizedFlags(self, conf):
         """Get dict of CXXFLAGS, LINKFLAGS, and DEFINES that are needed only in optimized mode"""
         return {'CXXFLAGS': [], 'LINKFLAGS': [], 'DEFINES': ['NDEBUG']}
@@ -246,6 +244,9 @@ def getDebugFlags(self, conf):
         elif self.getCompilerVersion(conf) >= (15, 0, 0):
             # https://releases.llvm.org/15.0.0/projects/libcxx/docs/UsingLibcxx.html#enabling-the-safe-libc-mode
             flags['DEFINES'] += ['_LIBCPP_ENABLE_ASSERTIONS=1']
+        # Tell libc++ to avoid including transitive headers
+        # https://libcxx.llvm.org/DesignDocs/HeaderRemovalPolicy.html
+        flags['DEFINES'] += ['_LIBCPP_REMOVE_TRANSITIVE_INCLUDES=1']
         return flags
 
     def getOptimizedFlags(self, conf):

.waf-tools/doxygen.py

@@ -1,9 +1,6 @@
-#! /usr/bin/env python
-# encoding: UTF-8
 # Thomas Nagy 2008-2010 (ita)
 
 """
-
 Doxygen support
 
 Variables passed to bld():
@@ -27,9 +24,8 @@ def doxygen(bld):
 			bld(features="doxygen", doxyfile='Doxyfile', ...)
 """
 
-from fnmatch import fnmatchcase
-import os, os.path, re, stat
-from waflib import Task, Utils, Node, Logs, Errors, Build
+import os, os.path, re
+from waflib import Task, Utils, Node
 from waflib.TaskGen import feature
 
 DOXY_STR = '"${DOXYGEN}" - '
@@ -207,8 +203,8 @@ def configure(conf):
 	conf.find_program('doxygen', var='DOXYGEN', mandatory=False)
 	conf.find_program('tar', var='TAR', mandatory=False)
 
-# doxygen docs
+# doxygen command
 from waflib.Build import BuildContext
 class doxy(BuildContext):
-    cmd = "doxygen"
-    fun = "doxygen"
+    cmd = 'doxygen'
+    fun = 'doxygen'

.waf-tools/sanitizers.py

@@ -1,4 +1,4 @@
-# -*- Mode: python; py-indent-offset: 4; indent-tabs-mode: nil; coding: utf-8; -*-
+# Davide Pesavento (LIP6), 2016
 
 def options(opt):
     opt.add_option('--with-sanitizer', action='store', default='', dest='sanitizers',

.waf-tools/sphinx.py

@@ -0,0 +1,77 @@
+# inspired by code by Hans-Martin von Gaudecker, 2012
+
+"""Support for Sphinx documentation"""
+
+import os
+from waflib import Task, TaskGen
+
+
+class sphinx_build(Task.Task):
+    color = 'BLUE'
+    run_str = '${SPHINX_BUILD} -q -b ${BUILDERNAME} -D ${VERSION} -D ${RELEASE} -d ${DOCTREEDIR} ${SRCDIR} ${OUTDIR}'
+
+    def keyword(self):
+        return f'Processing ({self.env.BUILDERNAME})'
+
+
+# from https://docs.python.org/3.12/whatsnew/3.12.html#imp
+def load_source(modname, filename):
+    import importlib.util
+    from importlib.machinery import SourceFileLoader
+    loader = SourceFileLoader(modname, filename)
+    spec = importlib.util.spec_from_file_location(modname, filename, loader=loader)
+    module = importlib.util.module_from_spec(spec)
+    loader.exec_module(module)
+    return module
+
+
+@TaskGen.feature('sphinx')
+@TaskGen.before_method('process_source')
+def process_sphinx(self):
+    """Set up the task generator with a Sphinx instance and create a task."""
+
+    conf = self.path.find_node(self.config)
+    if not conf:
+        self.bld.fatal(f'Sphinx configuration file {repr(self.config)} not found')
+
+    inputs = [conf] + self.to_nodes(self.source)
+    task = self.create_task('sphinx_build', inputs, always_run=getattr(self, 'always', False))
+
+    confdir = conf.parent.abspath()
+    buildername = getattr(self, 'builder', 'html')
+    srcdir = getattr(self, 'srcdir', confdir)
+    outdir = self.path.find_or_declare(getattr(self, 'outdir', buildername)).get_bld()
+    doctreedir = getattr(self, 'doctreedir', os.path.join(outdir.abspath(), '.doctrees'))
+    release = getattr(self, 'release', self.version)
+
+    task.env['BUILDERNAME'] = buildername
+    task.env['SRCDIR'] = srcdir
+    task.env['OUTDIR'] = outdir.abspath()
+    task.env['DOCTREEDIR'] = doctreedir
+    task.env['VERSION'] = f'version={self.version}'
+    task.env['RELEASE'] = f'release={release}'
+
+    if buildername == 'man':
+        confdata = load_source('sphinx_conf', conf.abspath())
+        for i in confdata.man_pages:
+            target = outdir.find_or_declare(f'{i[1]}.{i[4]}')
+            task.outputs.append(target)
+            if self.install_path:
+                self.bld.install_files(f'{self.install_path}/man{i[4]}/', target)
+    else:
+        task.outputs.append(outdir)
+
+    # prevent process_source from complaining that there is no extension mapping for .rst files
+    self.source = []
+
+
+def configure(conf):
+    """Check if sphinx-build program is available."""
+    conf.find_program('sphinx-build', var='SPHINX_BUILD', mandatory=False)
+
+
+# sphinx command
+from waflib.Build import BuildContext
+class sphinx(BuildContext):
+    cmd = 'sphinx'
+    fun = 'sphinx'

wscript

@@ -18,7 +18,7 @@ def options(opt):
     opt.load(['compiler_cxx', 'gnu_dirs'])
     opt.load(['default-compiler-flags',
               'coverage', 'sanitizers', 'boost',
-              'doxygen', 'sphinx_build'],
+              'doxygen', 'sphinx'],
              tooldir=['.waf-tools'])
 
     optgrp = opt.add_option_group('PSync Options')
@@ -34,7 +34,7 @@ def options(opt):
 def configure(conf):
     conf.load(['compiler_cxx', 'gnu_dirs',
                'default-compiler-flags', 'boost',
-               'doxygen', 'sphinx_build'])
+               'doxygen', 'sphinx'])
 
     conf.env.WITH_EXAMPLES = conf.options.with_examples
     conf.env.WITH_TESTS = conf.options.with_tests