Sphinx-generated documentation built in GitLab CI is sometimes defective
@pspacek noticed that the latest PDF version of the BIND 9 ARM is missing the entire "BIND 9 Configuration Reference" chapter:
https://ftp.isc.org/isc/bind9/9.17.9/doc/arm/Bv9ARM.pdf
The same problem seems to be affecting the PDF for 9.17.8:
https://ftp.isc.org/isc/bind9/9.17.8/doc/arm/Bv9ARM.pdf
but not for 9.17.7:
https://ftp.isc.org/isc/bind9/9.17.7/doc/arm/Bv9ARM.pdf
None of the 9.16.x PDFs seem to be broken this way.
I could not reproduce this problem locally and also confirmed there were
no changes in the doc/ directory between 9.17.7 and 9.17.8 that could
have caused this. Upon further investigation, I discovered that the
problem is caused by using parallel make jobs (-j) when running
make doc in GitLab CI - this causes multiple sphinx-build instances
to run simultaneously in the same working directory, which means they
can stomp on each other's data. Unfortunately, problems like this only
triggered Sphinx warnings, not errors, so the relevant GitLab CI jobs
have been silently passing.
This conclusion means that all forms of our documentation might have
been malformed in one way or another ever since we migrated to Sphinx,
i.e. since May 2020 (see !1761 (merged), !3536 (merged)). Looking at GitLab CI job traces
from the past 2 months, it can be estimated that the problem has a
roughly 15% chance of getting triggered for any Sphinx documentation
build job. (See correction below.)