From 4a9863e05397eaba46330e9ebeacad5e0e73f991 Mon Sep 17 00:00:00 2001 From: Laurent Pinchart Date: Wed, 17 Sep 2025 21:28:20 +0300 Subject: [PATCH] Documentation: Improve Sphinx and Doxygen integration 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 overriding conf.py with a custom version 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, with the toctree links and the links from Doxygen to Sphinx being broken already, and the links to API elements through doxylink now being broken too. This is considered as an acceptable compromise and an overall improvement. The installation directory is more important, as in the build tree people also have access to sources. Application developers in particular are less likely to read documentation from the libcamera build tree, they may not even have a copy of the libcamera source tree. 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 34fa3956..2c75a757 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 00000000..ea5a19dc --- /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 8cf77759..02277096 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,