From d19f16f2229b57afc5f3757e4bfdea48275e0597 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Barnab=C3=A1s=20P=C5=91cze?=
 <barnabas.pocze@ideasonboard.com>
Date: Thu, 31 Jul 2025 14:16:18 +0200
Subject: [PATCH] Documentation: Fix documentation generation when subproject
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The paths of the doxygen tag files for sphinxcontrib-doxygen must be
absolute or relative the the current working directory. However, when
libcamera is built as a subproject, the current working directory
is the top-level build directory. Thus the paths for the tag files
will not be correct.

Fix that by using `configure_file()` to generate the final sphinx
configuration with the appropriate paths queried from meson.

Fixes: 0382d215db7847 ("Documentation: Use Sphinx doxylink to generate links to doxygen")
Signed-off-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
---
 Documentation/{conf.py => conf.py.in} |  6 +++---
 Documentation/meson.build             | 17 +++++++++++++++--
 2 files changed, 18 insertions(+), 5 deletions(-)
 rename Documentation/{conf.py => conf.py.in} (95%)

diff --git a/Documentation/conf.py b/Documentation/conf.py.in
similarity index 95%
rename from Documentation/conf.py
rename to Documentation/conf.py.in
index f50be60a..097e579b 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py.in
@@ -74,11 +74,11 @@ pygments_style = None
 
 doxylink = {
     'doxy-pub': (
-        'Documentation/api-html/tagfile.xml',
+        '@TOP_BUILDDIR@/Documentation/api-html/tagfile.xml',
         '../api-html/',
     ),
     'doxy-int': (
-        'Documentation/internal-api-html/tagfile.xml',
+        '@TOP_BUILDDIR@/Documentation/internal-api-html/tagfile.xml',
         '../internal-api-html/',
     ),
 }
@@ -89,7 +89,7 @@ doxylink = {
 # a list of builtin themes.
 #
 html_theme = 'theme'
-html_theme_path = ['.']
+html_theme_path = ['@THEME_DIR@']
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
diff --git a/Documentation/meson.build b/Documentation/meson.build
index b898ba3a..10aaf613 100644
--- a/Documentation/meson.build
+++ b/Documentation/meson.build
@@ -142,11 +142,21 @@ if sphinx.found()
               .format(mod, version, min_version))
     endif
 
+    sphinx_conf = configure_file(input : 'conf.py.in',
+                                 output : 'conf.py',
+                                 configuration : {
+                                    'THEME_DIR': meson.current_source_dir(),
+                                    'TOP_BUILDDIR': meson.project_build_root(),
+                                 })
+
+    fs = import('fs')
+    sphinx_conf_dir = fs.parent(sphinx_conf)
+
     docs_sources = [
         'camera-sensor-model.rst',
         'code-of-conduct.rst',
         'coding-style.rst',
-        'conf.py',
+        sphinx_conf,
         'contributing.rst',
         'design/ae.rst',
         'documentation-contents.rst',
@@ -171,6 +181,7 @@ if sphinx.found()
 
     custom_target('documentation',
                   command : [sphinx, '-D', release, '-q', '-W', '-b', 'html',
+                             '-c', sphinx_conf_dir,
                              meson.current_source_dir(), '@OUTPUT@'],
                   input : docs_sources,
                   output : 'html',
@@ -184,7 +195,9 @@ if sphinx.found()
                   install_tag : 'doc')
 
     custom_target('documentation-linkcheck',
-                  command : [sphinx, '-W', '-b', 'linkcheck', meson.current_source_dir(), '@OUTPUT@'],
+                  command : [sphinx, '-W', '-b', 'linkcheck',
+                             '-c', sphinx_conf_dir,
+                             meson.current_source_dir(), '@OUTPUT@'],
                   build_always_stale : true,
                   input : docs_sources,
                   output : 'linkcheck')