From 6c56e07cbcc49541a453e0bd6000f7464d21e8bf Mon Sep 17 00:00:00 2001
From: Pekka Paalanen <pekka.paalanen@collabora.com>
Date: Thu, 29 Jan 2026 11:57:29 +0200
Subject: [PATCH] doc: make DocBook validation optional

It turns out that changes in the building environment, the version of
Doxygen being a prime suspect, can break the validation. Invalid DocBook
XML does lead to likely broken documentation, but perhaps it is better
than failing to build or having to disable documentation completely.

CI turns DocBook validation on, because the CI environment is stable and
known, and we do want to catch mistakes in hand-written DocBook files.

Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.com>
---
 .gitlab-ci.yml           | 2 +-
 doc/publican/meson.build | 7 ++++++-
 meson_options.txt        | 4 ++++
 3 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 39beeaf3..9816859a 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -159,7 +159,7 @@ armv7-debian-container_prep:
 # Core build environment.
 .build-env:
   variables:
-    MESON_BUILD_TYPE: "-Dbuildtype=debug -Doptimization=0 -Db_sanitize=address,undefined"
+    MESON_BUILD_TYPE: "-Dbuildtype=debug -Doptimization=0 -Db_sanitize=address,undefined -Ddocbook_validation=true"
     # See https://gitlab.freedesktop.org/wayland/wayland/-/merge_requests/154
     ASAN_OPTIONS: "detect_odr_violation=0"
   before_script:
diff --git a/doc/publican/meson.build b/doc/publican/meson.build
index 1aa31d3c..a572b0eb 100644
--- a/doc/publican/meson.build
+++ b/doc/publican/meson.build
@@ -94,11 +94,16 @@ foreach src : files([
 	)
 endforeach
 
+skip_validation = '--skip-validation'
+if get_option('docbook_validation')
+	skip_validation = []
+endif
+
 custom_target(
 	'Wayland-docbook-html',
 	command: [
 		xmlto,
-		'--skip-validation',
+		skip_validation,
 		'--stringparam', 'chunker.output.encoding=UTF-8',
 		'--stringparam', 'chunk.section.depth=0',
 		'--stringparam', 'toc.section.depth=1',
diff --git a/meson_options.txt b/meson_options.txt
index b8e2ec60..02c2346a 100644
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -14,6 +14,10 @@ option('documentation',
   description: 'Build the documentation (requires Doxygen, dot, xmlto, xsltproc)',
   type: 'boolean',
   value: true)
+option('docbook_validation',
+  type: 'boolean',
+  value: false,
+  description: 'Validate the intermediate DocBook XML during the documentation build')
 option('dtd_validation',
   description: 'Validate the protocol DTD (requires libxml2)',
   type: 'boolean',