When running "make" then building the documentation would fail with a message along the lines of "command not found: sphinx-build". Obviously, when sphinx-build is not available.
To make this a bit easier to get into, that is, building and viewing the documentation, then the Makefile is extended to build the documentation using sphinx-build from a Python venv local to the documentation.
Three pseudo-targets are facilitating this:
default
Provided as an explicit top-level to dispatch what happens by default. The default behavior is extended to install a Python venv.
venv
This installs the Python venv packages defined in requirements.txt. This is an actual make-target, thus when 'venv' exists, then this is skipped.
open
This attempts to open the build html docs via 'open' and 'xdg-open'
all
This will: install venv (when needed), build the html documentation, then attempt to open it.
With these changes then the default behavior of invoking "make" will provide an environment where calling "sphinx-build" will succeed. Thus, to bootstrap building the documentation the following is needed:
python3
python3-pip
python3-venv
This is expected to be provided by the system, e.g. via nix, a docker image, package installation or whatever one fancies.
When running "make" then building the documentation would fail with a message along the lines of "command not found: sphinx-build". Obviously, when sphinx-build is not available.
To make this a bit easier to get into, that is, building and viewing the documentation, then the Makefile is extended to build the documentation using sphinx-build from a Python venv local to the documentation.
Three pseudo-targets are facilitating this:
default
Provided as an explicit top-level to dispatch what happens by default. The default behavior is extended to install a Python venv.
venv
This installs the Python venv packages defined in requirements.txt. This is an actual make-target, thus when 'venv' exists, then this is skipped.
open
This attempts to open the build html docs via 'open' and 'xdg-open'
all
This will: install venv (when needed), build the html documentation, then attempt to open it.
With these changes then the default behavior of invoking "make" will provide an environment where calling "sphinx-build" will succeed. Thus, to bootstrap building the documentation the following is needed:
This is expected to be provided by the system, e.g. via nix, a docker image, package installation or whatever one fancies.