3.1.15. Sphinx

The tool is located in tools/waf-tools.

3.1.15.1. Tool Documentation

Implements a waf tool to use Sphinx.

f_sphinx_build.configure(conf)

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.Task

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

digraph ASM_TO_OBJECT {
    compound=true;
    rankdir=LR;
    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";
        rank=same;
        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.12 Input-output relation for conf.py

always_run = True

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

Type

str

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

Type

str

keyword()

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.

run()

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