From 440671e0d947b3602e26dd27d22fc347514c8192 Mon Sep 17 00:00:00 2001
From: Lars Michelsen <lm@checkmk.com>
Date: Tue, 17 Sep 2024 11:37:20 +0200
Subject: [PATCH] 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       |  2 +-
 doc/plugin-api/source/conf.py | 29 +++++++++++++++++++++++++++++
 2 files changed, 30 insertions(+), 1 deletion(-)

diff --git a/doc/plugin-api/Makefile b/doc/plugin-api/Makefile
index 8ee41c36138..c9032ef82ff 100644
--- a/doc/plugin-api/Makefile
+++ b/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
diff --git a/doc/plugin-api/source/conf.py b/doc/plugin-api/source/conf.py
index 2a7b7727006..cdf6efd2a41 100644
--- a/doc/plugin-api/source/conf.py
+++ b/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"]