Sphinx autodoc: Clean up warnings and enable fail-on-warning

Autodoc creates some warnings like this, which are not helpful and
silently produce empty API doc pages. To fix that, we ignore these
missing dependencies and suppress the other warnings which are shown
after the first step.

Now that we are warning clean, we enable `--fail-on-warning` to catch
any new warnings that are introduced.

Change-Id: Icaff604b9d3bae267f1e1b02ed1ad44f9b4415fc

doc/plugin-api/Makefile

@@ -11,7 +11,7 @@ PIPENV := $(REPO_PATH)/omd/run-pipenv
 
 # You can set these variables from the command line, and also
 # from the environment for the first one.
-SPHINXOPTS    ?=
+SPHINXOPTS    ?= --fail-on-warning
 SPHINXBUILD   := $(PIPENV) run sphinx-build
 BASEDIR       = $(REPO_PATH)/doc/plugin-api
 SOURCEDIR     = $(BASEDIR)/source

doc/plugin-api/source/conf.py

@@ -15,6 +15,7 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 
+import logging
 import os
 import sys
 
@@ -43,6 +44,34 @@
     "sphinx_rtd_theme",
 ]
 
+# Ignore unneeded dependencies during sphinx doc build time for now.
+#
+# The better way to deal with it would be to create a dedicated venv for the plugin API doc
+# generator which pulls in our packages as dependencies. This way we would ensure that all
+# dependencies are available during the sphinx execution. But since the documented modules
+# cmk.base.plugins.bakery.bakery_api, cmk.base.plugins.agent_based.agent_based_api and
+# cmk.cee.dcd.plugins.connectors.connectors_api are not separate packages right now, we can
+# not move on with this.
+autodoc_mock_imports = [
+    "cmk.trace",
+    "livestatus",
+    "cryptography",
+]
+
+suppress_warnings = [
+    # Our v1 and v2 APIs expose Result and Metric which is totally fine. Silence the warning.
+    "ref.python",
+]
+
+# The warnings "*:docstring of cmk.agent_based.v1._value_store_utils.GetRateError:1: WARNING:
+# duplicate object description of cmk.agent_based.v1._value_store_utils.GetRateError, other instance
+# in cmk.agent_based/v1, use :no-index: for one of them" is similar to the warning suppressed above
+# and built like this intentionally. Since this warning can not be suppressed using the sphinx
+# suppress_warnings feature we filter out the log message.
+logging.getLogger("sphinx").addFilter(
+    lambda s: "duplicate object description of cmk.agent_based.v1" not in s.getMessage()
+)
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]