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

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 { 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