From patchwork Sun Jul 27 01:57:13 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 23983 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 F2513BDCC1 for ; Sun, 27 Jul 2025 01:57:35 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 9336469127; Sun, 27 Jul 2025 03:57:35 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="KPoMvCKd"; 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 B97F269127 for ; Sun, 27 Jul 2025 03:57:31 +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 CEF69351 for ; Sun, 27 Jul 2025 03:56:50 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1753581411; bh=JgOGBfzVb57RE+D8FFhSwQIiELI91hPS2BZivaDjsys=; h=From:To:Subject:Date:In-Reply-To:References:From; b=KPoMvCKdqa6UOFFqeJIgmj3P/2/CjmVYWxlR117d+9th7GEYyrjKGMH/9dlTmXW5M hxxZqKqumGlXOATqCu4YYm3Hu2Ko1JFsuHgQq232MMXa19mgZq+4tYe72rDsOiDStn H29Vn02ZNU2DUhW1C3hzNinJD64YDZ8HRW1WKpDM= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Subject: [PATCH 3/4] Documentation: Use Sphinx doxylink to generate links to doxygen Date: Sun, 27 Jul 2025 04:57:13 +0300 Message-ID: <20250727015720.6867-4-laurent.pinchart@ideasonboard.com> X-Mailer: git-send-email 2.49.1 In-Reply-To: <20250727015720.6867-1-laurent.pinchart@ideasonboard.com> References: <20250727015720.6867-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 Sphinx documentation needs to link to the API documentation generated by Doxygen. The links currently point to the documentation hosted on the official https://libcamera.org/ website. This causes multiple issues: - Doxygen generates URLs with MD5 hashes of function signatures, making the link targets unstable. - When testing documentation builds that include API changes, links to new API elements will be broken. - The generated documentation can't be browsed offline. Fix this by using the Sphinx doxylink extension. This allows specifying link targets as class and function names, with the link being automatically generated using the same MD5 hashing as Doxygen. The root of the link target is configured in a central location, which defaults to the build directory and can be overridden to point to the libcamera website when pushing the documentation. This commit only introduces the infrastructure to use doxylink. Manual links will be replaced separately. Signed-off-by: Laurent Pinchart --- Documentation/Doxyfile-internal.in | 2 ++ Documentation/Doxyfile-public.in | 2 ++ Documentation/conf.py | 13 +++++++- Documentation/meson.build | 48 ++++++++++++++++-------------- README.rst | 3 +- 5 files changed, 44 insertions(+), 24 deletions(-) diff --git a/Documentation/Doxyfile-internal.in b/Documentation/Doxyfile-internal.in index 5343bc2b131c..a422bb0719da 100644 --- a/Documentation/Doxyfile-internal.in +++ b/Documentation/Doxyfile-internal.in @@ -3,6 +3,8 @@ @INCLUDE_PATH = @TOP_BUILDDIR@/Documentation @INCLUDE = Doxyfile-common +GENERATE_TAGFILE = @TOP_BUILDDIR@/Documentation/internal-api-html/tagfile.xml + HIDE_UNDOC_CLASSES = NO HIDE_UNDOC_MEMBERS = NO HTML_OUTPUT = internal-api-html diff --git a/Documentation/Doxyfile-public.in b/Documentation/Doxyfile-public.in index 36bb57584a07..c3a8b0dd003a 100644 --- a/Documentation/Doxyfile-public.in +++ b/Documentation/Doxyfile-public.in @@ -3,6 +3,8 @@ @INCLUDE_PATH = @TOP_BUILDDIR@/Documentation @INCLUDE = Doxyfile-common +GENERATE_TAGFILE = @TOP_BUILDDIR@/Documentation/api-html/tagfile.xml + HIDE_UNDOC_CLASSES = YES HIDE_UNDOC_MEMBERS = YES HTML_OUTPUT = api-html diff --git a/Documentation/conf.py b/Documentation/conf.py index 870937289eb4..f50be60a1559 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -37,7 +37,8 @@ author = 'The libcamera documentation authors' # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - 'sphinx.ext.graphviz' + 'sphinx.ext.graphviz', + 'sphinxcontrib.doxylink', ] graphviz_output_format = 'svg' @@ -71,6 +72,16 @@ exclude_patterns = [ # The name of the Pygments (syntax highlighting) style to use. pygments_style = None +doxylink = { + 'doxy-pub': ( + 'Documentation/api-html/tagfile.xml', + '../api-html/', + ), + 'doxy-int': ( + 'Documentation/internal-api-html/tagfile.xml', + '../internal-api-html/', + ), +} # -- Options for HTML output ------------------------------------------------- diff --git a/Documentation/meson.build b/Documentation/meson.build index 3afdcc1a87af..87918bf9a921 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -81,16 +81,16 @@ if doxygen.found() and dot.found() '@INPUT@', ]) - custom_target('doxygen-public', - input : [ - doxyfile, - doxyfile_common, - ], - output : 'api-html', - command : [doxygen, doxyfile], - install : true, - install_dir : doc_install_dir, - install_tag : 'doc') + doxygen_public = custom_target('doxygen-public', + input : [ + doxyfile, + doxyfile_common, + ], + output : 'api-html', + command : [doxygen, doxyfile], + install : true, + install_dir : doc_install_dir, + install_tag : 'doc') # This is the internal documentation, which hard-codes a list of directories # to parse in its doxyfile. @@ -99,18 +99,18 @@ if doxygen.found() and dot.found() output : 'Doxyfile-internal', configuration : cdata) - custom_target('doxygen-internal', - input : [ - doxyfile, - doxyfile_common, - doxygen_public_input, - doxygen_internal_input, - ], - output : 'internal-api-html', - command : [doxygen, doxyfile], - install : true, - install_dir : doc_install_dir, - install_tag : 'doc-internal') + doxygen_internal = custom_target('doxygen-internal', + input : [ + doxyfile, + doxyfile_common, + doxygen_public_input, + doxygen_internal_input, + ], + output : 'internal-api-html', + command : [doxygen, doxyfile], + install : true, + install_dir : doc_install_dir, + install_tag : 'doc-internal') endif # @@ -154,6 +154,10 @@ if sphinx.found() input : docs_sources, output : 'html', build_by_default : true, + depends : [ + doxygen_public, + doxygen_internal, + ], install : true, install_dir : doc_install_dir, install_tag : 'doc') diff --git a/README.rst b/README.rst index e2a6e275895e..e9a7dd82de74 100644 --- a/README.rst +++ b/README.rst @@ -67,7 +67,8 @@ for device hotplug enumeration: [optional] libudev-dev for documentation: [optional] - python3-sphinx doxygen graphviz texlive-latex-extra + doxygen graphviz python3-sphinx python3-sphinxcontrib.doxylink (>= 1.6.1) + texlive-latex-extra for gstreamer: [optional] libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev