Skip to content

Do not use parallel make jobs for building docs

Michał Kępień requested to merge 2448-do-not-use-parallel-make-jobs-for-building-docs into main

Concurrently running sphinx-build instances started in the same working directory are not separated from each other in any way. This can cause intermittent problems which we failed to notice before because they only trigger Sphinx warnings, not errors, e.g.:

WARNING: toctree contains ref to nonexisting file 'reference'

The message above is not triggered because doc/arm/reference.rst is actually missing from disk at any point, but rather because a temporary file created by one sphinx-build instance gets truncated by another one working in parallel (the confusing message quoted above is logged because of an overly broad "except" statement in Sphinx code).

Drop the -j command line switch from the make invocation used for building documentation to prevent intermittent problems caused by multiple sphinx-build instances running simultaneously in the same working directory.

Also drop the -k command line switch from the same make invocation while we are at it as that switch does not bring any practical value in this case.

Closes #2448 (closed)

Merge request reports