qdoc: Introduce 'warninglimit' configuration variable

This variable is primarily meant for testing the documentation builds
in the CI system; if the warning count exceeds the set limit, QDoc
uses the total number of warnings as exit code.

The warning limit is enforced when either warninglimit.enabled = true,
or QDOC_ENABLE_WARNINGLIMIT environment variable is set.

This also provides a method to override the CI failing a documentation
build; the author can increase the warning limit to let the build
pass, hopefully with a good excuse in the code review.

Change-Id: If455a9636f2c63b41798523dd4acb3183a00229c
Reviewed-by: Martin Smith <martin.smith@qt.io>
Reviewed-by: Frederik Gladhorn <frederik.gladhorn@qt.io>

1 files changed, 26 insertions, 0 deletions

diff --git a/src/qdoc/doc/qdoc-manual-qdocconf.qdoc b/src/qdoc/doc/qdoc-manual-qdocconf.qdoc
index cbb233d8d..d61483f44 100644
--- a/src/qdoc/doc/qdoc-manual-qdocconf.qdoc
+++ b/src/qdoc/doc/qdoc-manual-qdocconf.qdoc
@@ -122,6 +122,7 @@
     \li \l {tabsize-variable} {tabsize}
     \li \l {version-variable} {version}
     \li \l {versionsym-variable} {versionsym}
+    \li \l {warninglimit-variable} {warninglimit}
     \endlist
 
     \section1 Categories
@@ -1120,6 +1121,31 @@
     implemented. Currently, it only works within raw HTML code.
 
     See also \l {version} {\\version}.
+
+    \target warninglimit-variable
+    \section1 warninglimit
+
+    The \c warninglimit variable sets the maximum number of documentation
+    warnings allowed. If this limit is exceeded, QDoc continues as normal
+    but exits with the warning count as the error code. If the limit was
+    not exceeded or \c warninglimit was not defined, QDoc process exits
+    with 0, assuming there were no other critical errors.
+
+    Setting the \c warninglimit to \c 0 means failure on any warning.
+
+    \note By default, QDoc does not enforce the warning limit. Enable it
+    with \c {warninglimit.enabled = true} or by defining
+    the \c QDOC_ENABLE_WARNINGLIMIT environment variable.
+
+    For example,
+
+    \badcode
+    # Fail the documentation build if we have more than 100 warnings
+    warninglimit = 100
+    warninglimit.enabled = true
+    \endcode
+
+    The \c warninglimit variable was introduced in Qt 5.11.
 */
 
 /*!