Use Read the Docs command to build Sphinx documents in parallel

[madmiraal]

Read the Docs, which hosts our online documentation: https://docs.rebeltoolbox.com has limits on the resources available to a build the documentation. Builds will fail if they take longer than 30 minutes. Our builds are currently taking around 30 minutes and have taken longer and failed e.g.: https://readthedocs.org/projects/rebel-documentation/builds/23365172/.

The majority of the time is taken up by the Sphinx build:

Date: 2024-02-06T00:39:55.838316Z
...
[rtd-command-info] start-time: 2024-02-06T00:40:38.959622Z, end-time: 2024-02-06T01:10:03.989662Z, duration: 1765, exit-code: 0
python -m sphinx -T -b html -d _build/doctrees -D language=en . $READTHEDOCS_OUTPUT/html

Everything before the Sphinx build is taking less than a minute, but the build is taking close to half an hour, with the failed build exceeding the 30 minute limit:

Date: 2024-02-06T18:28:43.194512Z
...
[rtd-command-info] start-time: 2024-02-06T18:29:29.603841Z, end-time: 2024-02-06T19:00:33.754201Z, duration: 1864, exit-code: 137
python -m sphinx -T -b html -d _build/doctrees -D language=en . $READTHEDOCS_OUTPUT/html

This PR attempts to use a custom build command to run the Sphinx build using multiple parallel jobs. I have tested this command using a GitHub build test, which ran for only 11 minutes! However, this can only be tested on Read the Docs once the PR is created.

[madmiraal]

Closing, because running parallel builds does not significantly reduce the build time. Most of the time is spent writing the files; so this is an I/O bottle-neck not a processing bottle-neck.

Read the Docs has kindly extended our allowed build times. So, builds should no longer fail for taking slightly longer than 30 minutes going forward.