Documentation build hides reStructuredText syntax errors #521

Description

doc/conf.py sets suppress_warnings = ["docutils"]. The documentation build therefore succeeds with -W even when the reStructuredText is invalid (e.g. title underlines that are too short, or a title directly followed by a list), so such errors go unnoticed and may change the rendering.

Expected behavior

Syntax errors of the documentation sources are reported by the build.

Proposed change

Find out why the docutils warnings were suppressed (e.g. warnings raised by third-party docstrings), fix the remaining errors and restrict the suppression to what is necessary.