From patchwork Wed Sep 17 20:17:38 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 24385 Return-Path: X-Original-To: parsemail@patchwork.libcamera.org Delivered-To: parsemail@patchwork.libcamera.org Received: from lancelot.ideasonboard.com (lancelot.ideasonboard.com [92.243.16.209]) by patchwork.libcamera.org (Postfix) with ESMTPS id E5E3BC328C for ; Wed, 17 Sep 2025 20:18:33 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id D63AA69382; Wed, 17 Sep 2025 22:18:32 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="iIAwUDKX"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 97CA069379 for ; Wed, 17 Sep 2025 22:18:23 +0200 (CEST) Received: from pendragon.ideasonboard.com (81-175-209-231.bb.dnainternet.fi [81.175.209.231]) by perceval.ideasonboard.com (Postfix) with UTF8SMTPSA id 7259F6A8 for ; Wed, 17 Sep 2025 22:17:04 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1758140224; bh=N376aSK3qfu1wiTEhislzcSsHMcg6yFxbo6+C/X4bHo=; h=From:To:Subject:Date:In-Reply-To:References:From; b=iIAwUDKXiuXWZyysQYiS9vDXl8LseyomQanpr3nT7jo1suLFxfIl7vDvxyzWY/O/C 0EceE33MPJ86zYKYxPrcT2rBoXoT4Kbh6tRf8oNN7Xe4+gApZCnl1PWOKF4g0VYVhf wpWPQzvV857Tzz1f7tCWHPseFH+pCJRYDakg4Z3U= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Subject: [PATCH v3 07/10] Documentation: Improve Sphinx and Doxygen integration Date: Wed, 17 Sep 2025 23:17:38 +0300 Message-ID: <20250917201742.16406-8-laurent.pinchart@ideasonboard.com> X-Mailer: git-send-email 2.49.1 In-Reply-To: <20250917201742.16406-1-laurent.pinchart@ideasonboard.com> References: <20250917201742.16406-1-laurent.pinchart@ideasonboard.com> MIME-Version: 1.0 X-BeenThere: libcamera-devel@lists.libcamera.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" The libcamera documentation comprises two parts: pages generated by Sphinx into the Documentation/html/ directory within the build tree, and API reference documentation generated by Doxygen into Documentation/internal-api-html/ and Documentation/api-html/. The two parts are generated separately, but link to each other. From Sphinx to Doxygen, we use the doxylink extension for Sphinx to generate links to the Doxygen pages corresponding to API elements. The extension needs to be configured with the paths to the Doxygen documentation, which are set based on the html/, api-html/ and internal-api-html/ directories being placed side by side in the same parent directory. Furthermore, we also want to link to the API documentation from the Sphinx toctree. As toctrees can only link to pages within the Sphinx documents tree (or to http URLs), we have placeholder .rst documents for api-html and internal-api-html in the Sphinx documentation tree. Those generate the Documentation/html/internal-api-html/index.html and Documentation/html/api-html/index.html placeholder files in the build tree. The other way around, the API documentation's introduction pagelinks to Sphinx pages using relative paths. Those paths are hardcoded based on the api-html/ and internal-api-html/ directories being children of the html/ directory. This results in links being broken in different ways in the build tree, as well as in the installation directory: the toctree links direct to the placeholder pages within the html/ directory instead of the Doxygen documentation in sibling directories, and the Doxygen introduction links to Sphinx are simply broken. When publishing documentation on the website we work around those issues by patching several files and moving the api-html/ and internal-api-html/ directories to the html/ directory. Fixing this is surprisingly difficult. The toctree links can't be changed to point to a path outside of the Sphinx document tree as this isn't supported by Sphinx. Using http URLs would link to the libcamera.org website inside of local documentation, which isn't acceptable. It may be possible to develop a Sphinx extension to patch the toctree after it gets parsed, but that would be complex and likely fragile. Modifying the install path of the Doxygen documentation to html/api-html/ and html/internal-api-html/ causes issues as the Sphinx documentation will then overwrite the Doxygen index.html files with the placeholder indexes. Creating symlinks from html/api-html/ to api-html/ in the installation directory causes similar problems if 'meson install' is run twice. Creating the symlinks in the build directory (which was attempted with a custom Sphinx extension) is also a no-go: starting with meson v1.8.0, installing symlinks to directories causes an exception due to a bug in meson. The right solution is probably to investigate usage of the doxysphinx extension. As that's no small amount of work, let's start with a non-perfect but simple improvement: configure doxylink based on the api-html/ and internal-api-html/ directories being children of the Sphinx html/ documentation, and move those two API documentation directories to html/ during installation with a post-install script. This fixes links in the installation directory. Links in the build directory remain broken, but that is not a regression. Signed-off-by: Laurent Pinchart Reviewed-by: Stefan Klug --- Documentation/conf.py.in | 4 ++-- Documentation/install-doxygen.sh | 18 ++++++++++++++++++ Documentation/meson.build | 3 +++ 3 files changed, 23 insertions(+), 2 deletions(-) create mode 100755 Documentation/install-doxygen.sh diff --git a/Documentation/conf.py.in b/Documentation/conf.py.in index 34fa3956f49e..2c75a75799e6 100644 --- a/Documentation/conf.py.in +++ b/Documentation/conf.py.in @@ -75,11 +75,11 @@ pygments_style = None doxylink = { 'doxy-pub': ( '@TOP_BUILDDIR@/Documentation/api-html/tagfile.xml', - '../api-html/', + 'api-html/', ), 'doxy-int': ( '@TOP_BUILDDIR@/Documentation/internal-api-html/tagfile.xml', - '../internal-api-html/', + 'internal-api-html/', ), } diff --git a/Documentation/install-doxygen.sh b/Documentation/install-doxygen.sh new file mode 100755 index 000000000000..ea5a19dc8fda --- /dev/null +++ b/Documentation/install-doxygen.sh @@ -0,0 +1,18 @@ +#!/bin/sh +# SPDX-License-Identifier: GPL-2.0-or-later +# Copyright (C) 2025, Ideas on Board Oy +# +# Author: Laurent Pinchart +# +# Move Doxygen-generated API documentation to correct location + +doc_dir="${MESON_INSTALL_DESTDIR_PREFIX}/$1" +shift +dirs="$*" + +echo "Moving API documentation" + +for dir in $dirs ; do + rm -r "${doc_dir}/html/${dir}" + mv "${doc_dir}/${dir}" "${doc_dir}/html/" +done diff --git a/Documentation/meson.build b/Documentation/meson.build index 8cf7775902f3..022770968fcf 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -193,6 +193,9 @@ if sphinx.found() install_dir : doc_install_dir, install_tag : 'doc') + meson.add_install_script('install-doxygen.sh', doc_install_dir, + 'api-html', 'internal-api-html') + custom_target('documentation-linkcheck', command : [sphinx, '-W', '-b', 'linkcheck', '-c', sphinx_conf_dir,