2.1.5. Sphinx

The tool is located in tools/waf-tools.

2.1.5.1. Tool Documentation

Implements a waf tool to use Sphinx.

sphinx_build.configure(ctx: waflib.Configure.ConfigurationContext)

Find ‘sphinx-build’ executable.

sphinx_build.find_sphinx_build(ctx: waflib.Configure.ConfigurationContext)

Find the ‘sphinx-build’ executable and determine its version.

sphinx_build.get_sphinx_build_version(ctx: waflib.Configure.ConfigurationContext)

Determine ‘sphinx-build’ version

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

Bases: 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_conf_py [label="conf.py", style=filled]; nd_out_dir [label="OUTDIR/index.html", style=filled]; subgraph cluster_cmd { label = "Command Line"; rank=same; nd_builder_name [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_builder_name [lhead=cluster_cmd]; nd_conf_py -> nd_builder_name [lhead=cluster_cmd]; nd_builder_name -> nd_out_dir [ltail=cluster_cmd]; }

Fig. 2.8 Input-output relation for conf.py

always_run = True

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

Type:

str

color = 'BLUE'

color in which the command line is displayed in the terminal

Type:

str

run()

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