3.1.12. Waf Tool Sphinx

The tool is located in tools/waf-tools. Tool Documentation

Implements a waf tool to use Sphinx.


Set up the task generator with a Sphinx instance and create a task.


Check if the following programs are available

  • sphinx-build,

  • dot

f_sphinx_build.rst(self, node)

dummy function to be able to use bld(features="sphinx", source="abc*.rst", ...).

class f_sphinx_build.sphinx_task(*args: Any, **kwargs: Any)

Bases: waflib.Task.

class to compile a conf.py file into documentation using Sphinx.

digraph ASM_TO_OBJECT {
    nd_sphinx [label="sphinx_build", style=filled, fillcolor=green];
    nd_confpy  [label="conf.py", style=filled];
    nd_outdir  [label="OUTDIR/index.html", style=filled];
    subgraph cluster_cmd {
        label = "Command Line";
        nd_buildername  [label="BUILDERNAME"];
        nd_version      [label="VERSION"];
        nd_release      [label="RELEASE"];
        nd_dot          [label="DOT"];
        nd_doctreedir   [label="DOCTREEDIR"];
        nd_srcdir       [label="SRCDIR"];
    nd_sphinx       -> nd_buildername   [lhead=cluster_cmd];
    nd_confpy       -> nd_buildername   [lhead=cluster_cmd];
    nd_buildername  -> nd_outdir        [ltail=cluster_cmd];

Fig. 3.5 Input-output relation for conf.py

always_run = True

Sphinx handles the need for a re-run, so always run this task



check_output_html(std_out, std_err)

check if the html task generates any real errors

check_output_linkcheck(std_out, std_err)

check if the linkcheck task generates any real errors

check_output_spelling(std_out, std_err)

check if the spelling task generates any real errors

color = 'BLUE'

color in which the command line is displayed in the terminal




displayed keyword when the sphinx configuration file is compiled

static removedinsphinx30warning(_str)

The warning RemovedInSphinx30Warning is not a valid warning in our build therefore it can skipped to fail the build.


Creates a command line processed by Utils.subprocess.Popen in order to build the sphinx documentation. See Fig. 3.5 for a simplified representation