docbuild aborting on warnings

[Antonio Rojas]

Sage doc build currently aborts by default whenever sphinx emits a warning, and keeps a hardcoded whitelist of "admissible" warnings that needs to be kept up to date. This is very inconvenient for distros building Sage with system Sphinx, as every new version introduces new warnings: a fix was just committed for Sphinx 4.3 and now it is broken again with 4.4 due to new warnings.

This is equivalent to adding "-Werror" in C/C++ build flags of released software, which is widely regarded as bad practice, as there is a high change of breakage when updating the compiler. Can we please reconsider this policy? Fixing the warnings can still be a requirement for accepting tickets upgrading Sage's bundled Sphinx, but this would make things less painful for distributions.

[Matthias Koeppe]

+1 on this as a new default if we add a flag for the current strict behavior, for use by Release Manager, patchbot, and GH Actions.

[Michael Orlitzky]

On Tue, 2022-02-01 at 16:10 -0800, Matthias Koeppe wrote:
> +1 on this as a new default if we add a flag for the current strict
> behavior, for use by Release Manager, patchbot, and GH Actions.
>

We could also explicitly list the warnings that can cause a failure,
but that might get annoying fast.