Project:Python/Sphinx race conditions

Packages using Sphinx to generate documentation, e.g. via Makefiles are frequently subject to race conditions.

Symptoms
This happens because multiple Sphinx instances are running in parallel, and they happen to be attempting to create the same directory.

Problem
Sphinx is not designed to be parallel-safe. This has been reported upstream as issue 2946, however no fix is expected soon. If you run two Sphinx instances using the same doctree in parallel, they will race for it, and either one will overwrite the other's one work, or they will hit a failing mkdir or like.

Use -j1
The easy workaround is… not to run Sphinx in parallel. For example, when you're calling make to build docs, pass -j1:

Force separate doctrees
This is the hard solution. Each sphinx-build invocation is passed a -d parameter that specifies the doctree directory. You need to alter the Makefiles to make sure that every invocation that can happen in parallel uses a different directory.

Good news is that if you do that, you have a good chance of getting it merged upstream.