From patchwork Thu Sep 11 23:01:07 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 24335 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 25EEDC324E for ; Thu, 11 Sep 2025 23:01:59 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 2486969380; Fri, 12 Sep 2025 01:01:58 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="wSCAK5Ow"; 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 CC4B06936E for ; Fri, 12 Sep 2025 01:01:52 +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 B79CC4579 for ; Fri, 12 Sep 2025 01:00:37 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1757631637; bh=T3oHH2BBgxsWfdixafQQNiR67XuNBweueWURidmbNs8=; h=From:To:Subject:Date:In-Reply-To:References:From; b=wSCAK5OwNKVi3LTO4YIftNltjkb9aE2vM94rRsN7WcbafXIg4VRB8wkeAZEEktFNP St8/S3yjV5Dm8B5jlhnPM073q/AvCD6uCZ/Mwlegus1GtuH9FRLBhT4XOPXbkdFHi3 Qz65C7l8P5p/WmBhHCr8suW/NX+XDtSq2Z5MwxDo= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Subject: [PATCH v2 06/10] Documentation: Install API documentation within HTML directory Date: Fri, 12 Sep 2025 02:01:07 +0300 Message-ID: <20250911230115.25335-7-laurent.pinchart@ideasonboard.com> X-Mailer: git-send-email 2.49.1 In-Reply-To: <20250911230115.25335-1-laurent.pinchart@ideasonboard.com> References: <20250911230115.25335-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 is made of high-level documentation and guides, written as ReStructuredText and compiled to HTML by Sphinx, and API reference documentation, written as comments in the code and compiled to HTML by Doxygen. Due to meson limitations that make it difficult to place output files in subdirectories, the compilation process produces an html/ directory for the Sphinx documentation, and api-html/ and internal-api-html/ directories for the Doxygen documentation. When deploying the documentation to the libcamera.org website, the api-html and internal-api-html/ directories are moved within html/ to make the documentation self-contained. The Sphinx and Doxygen documentation link to each other. The links are generated using relative paths, based on the directory hierarchy on the website. This makes them broken when navigating the documentation in the build tree or in the directory where libcamera is installed. Fix this by standardizing on the directories hierarchy of the website in the build and install directories: - For the build directory, we can't easily build the Doxygen documentation in a subdirectory of the Sphinx documentation due to limitations of meson. Keep the existing output directories, and replace the html/api-html/ and html/internal-api-html/ placeholder directories with symlinks to the Doxygen output directories. This is handled by a small custom Sphinx extension. - For the install directory, install the Doxygen documentation to html/api-html/ and html/internal-api-html/. This overwrites the placeholders. Signed-off-by: Laurent Pinchart --- Changes since v1: - Split from "[PATCH 4/6] documentation: Include API docs in the sphinx documentation" - Avoid copying the doxygen documentation - Use a sphinx extension to generate symlinks --- Documentation/conf.py.in | 26 +++++---- Documentation/extensions/doxygen-link.py | 73 ++++++++++++++++++++++++ Documentation/meson.build | 19 ++++-- 3 files changed, 104 insertions(+), 14 deletions(-) create mode 100644 Documentation/extensions/doxygen-link.py diff --git a/Documentation/conf.py.in b/Documentation/conf.py.in index 34fa3956f49e..5e0a7cff2984 100644 --- a/Documentation/conf.py.in +++ b/Documentation/conf.py.in @@ -9,14 +9,8 @@ # -- Path setup -------------------------------------------------------------- -# If extensions (or modules to document with autodoc) are in another directory, -# 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 os -# import sys -# sys.path.insert(0, os.path.abspath('.')) - +import sys +sys.path.insert(0, "@CURRENT_SRCDIR@/extensions") # -- Project information ----------------------------------------------------- @@ -39,6 +33,7 @@ author = 'The libcamera documentation authors' extensions = [ 'sphinx.ext.graphviz', 'sphinxcontrib.doxylink', + 'doxygen-link', ] graphviz_output_format = 'svg' @@ -75,14 +70,25 @@ 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/', ), } +doxygen_links = [ + [ + '@TOP_BUILDDIR@/Documentation/html/api-html', + '@TOP_BUILDDIR@/Documentation/api-html', + ], + [ + '@TOP_BUILDDIR@/Documentation/html/internal-api-html', + '@TOP_BUILDDIR@/Documentation/internal-api-html', + ], +] + # -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for diff --git a/Documentation/extensions/doxygen-link.py b/Documentation/extensions/doxygen-link.py new file mode 100644 index 000000000000..8b94a4dd7f0b --- /dev/null +++ b/Documentation/extensions/doxygen-link.py @@ -0,0 +1,73 @@ +# SPDX-License-Identifier: GPL-2.0-or-later +# Copyright (C) 2025, Ideas on Board Oy + +import contextlib +import os +import shutil +from pathlib import Path +from sphinx.util import logging + +__version__ = "0.0.0" + +logger = logging.getLogger(__name__) + + +def on_config_inited(app, config): + entries = [] + + outdir = Path(app.outdir).absolute() + + for index, items in enumerate(config.doxygen_links): + err_msg_prefix = f'Config variable `doxygen_links` contains invalid entry {index} (`{items}`)' + + if len(items) != 2: + raise ValueError(f'{err_msg_prefix}: expected (path, target)') + + path = Path(items[0]).absolute() + target = Path(items[1]).relative_to(path.parent, walk_up=True) + + if not path.is_relative_to(outdir): + raise ValueError(f'{err_msg_prefix}: path `{items[0]}` is outside of output directory `{outdir}`') + + entries.append([path, target]) + + config.doxygen_links = entries + + +def on_builder_inited(app): + # Remove the symlinks if they exist, to avoid overwriting the index.html + # generated by Doxygen with the placeholder index from Sphinx. + + for path, target in app.config.doxygen_links: + if path.is_symlink(): + logger.info(f'Removing existing symlink {path}') + os.unlink(path) + + +def on_build_finished(app, exc): + # Create the symlinks. Remove any existing placeholder directory + # recursively first. + + if exc: + return + + for path, target in app.config.doxygen_links: + logger.info(f'Creating symlink {path} -> {target}') + + if path.is_dir(): + shutil.rmtree(path) + + os.symlink(target, path) + + +def setup(app): + app.add_config_value('doxygen_links', [], 'env', frozenset({list, tuple})) + app.connect('config-inited', on_config_inited) + app.connect('builder-inited', on_builder_inited) + app.connect('build-finished', on_build_finished) + + return { + "version": __version__, + "parallel_read_safe": True, + "parallel_write_safe": True, + } diff --git a/Documentation/meson.build b/Documentation/meson.build index f73407432fff..82d76b257b8c 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -12,6 +12,7 @@ dot = find_program('dot', required : get_option('documentation')) if doxygen.found() and dot.found() cdata = configuration_data() cdata.set('VERSION', 'v@0@'.format(libcamera_git_version)) + cdata.set('CURRENT_SRCDIR', meson.current_source_dir()) cdata.set('TOP_SRCDIR', meson.project_source_root()) cdata.set('TOP_BUILDDIR', meson.project_build_root()) cdata.set('OUTPUT_DIR', meson.current_build_dir()) @@ -89,7 +90,7 @@ if doxygen.found() and dot.found() output : 'api-html', command : [doxygen, doxyfile], install : true, - install_dir : doc_install_dir, + install_dir : doc_install_dir / 'html', install_tag : 'doc') # This is the internal documentation, which hard-codes a list of directories @@ -109,7 +110,7 @@ if doxygen.found() and dot.found() output : 'internal-api-html', command : [doxygen, doxyfile], install : true, - install_dir : doc_install_dir, + install_dir : doc_install_dir / 'html', install_tag : 'doc-internal') endif @@ -149,7 +150,11 @@ if sphinx.found() fs = import('fs') sphinx_conf_dir = fs.parent(sphinx_conf) + sphinx_env = environment() + sphinx_env.set('PYTHONDONTWRITEBYTECODE', '1') + docs_sources = [ + 'api-html/index.rst', 'camera-sensor-model.rst', 'code-of-conduct.rst', 'coding-style.rst', @@ -164,6 +169,7 @@ if sphinx.found() 'guides/pipeline-handler.rst', 'guides/tracing.rst', 'index.rst', + 'internal-api-html/index.rst', 'introduction.rst', 'lens_driver_requirements.rst', 'libcamera_architecture.rst', @@ -183,10 +189,14 @@ if sphinx.found() input : docs_sources, output : 'html', build_by_default : true, + depend_files : [ + 'extensions/doxygen-link.py', + ], depends : [ doxygen_public, doxygen_internal, ], + env : sphinx_env, install : true, install_dir : doc_install_dir, install_tag : 'doc') @@ -195,7 +205,8 @@ if sphinx.found() command : [sphinx, '-W', '-b', 'linkcheck', '-c', sphinx_conf_dir, meson.current_source_dir(), '@OUTPUT@'], - build_always_stale : true, input : docs_sources, - output : 'linkcheck') + output : 'linkcheck', + build_always_stale : true, + env : sphinx_env) endif