From patchwork Tue Jul 29 20:42:23 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 24031 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 5152ABDC71 for ; Tue, 29 Jul 2025 20:42:40 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 0622B691F0; Tue, 29 Jul 2025 22:42:39 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="SH2iOU+4"; 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 85C0869052 for ; Tue, 29 Jul 2025 22:42:37 +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 5681B42B for ; Tue, 29 Jul 2025 22:41:54 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1753821714; bh=jZTexdGtP3N1iD27EZS2YDDzRicjNBIxRLq6OPxHBSg=; h=From:To:Subject:Date:From; b=SH2iOU+42sehvzlXrj+eS7j3gfOs/CpKMpAXdxPv2zHVGrdb+I1ogxJmuHS22Qtlm LS6QI3B54v/DntOEFTWbnakQ/00gUkzyZ3qghoN8zMOpjQlGA2Ym6hQAwaOBAU6TNX lXZdMzI78auBOWDZ0cYy/9taxkSzIIXZHndHbjvY= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Subject: [PATCH v2 0/4] Documentation: Use doxylink to generate Sphinx-to-Doxygen links Date: Tue, 29 Jul 2025 23:42:23 +0300 Message-ID: <20250729204228.23217-1-laurent.pinchart@ideasonboard.com> X-Mailer: git-send-email 2.49.1 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" Hello, This patch series fixes a long-standing issue in the libcamera Sphinx documentation: links from Sphinx to Doxygen. While links between Sphinx pages are generated by Sphinx, and links within the API documentation are generated by Doxygen, links from Sphinx to Doxygen are currently manual, and point to the libcamera.org website. This causes links to regularly break, and prevents testing documentation builds fully offline. The doxylink Sphinx extension module comes to the rescue. It allows referencing the Doxygen documentation from within Sphinx documents, using a custom role. The series starts with two small cleanups of the Sphinx configuration in patches 1/4 and 2/4. Patch 3/4 then enables doxylink in the build system and in the Sphinx configuration, and patch 4/4 replaces manual links. The main drawback with this solution is the new dependency on doxylink. The module is packaged by Debian, but the version in Bookworm is not compatible with the Sphinx version shipped by the same distribution (doxylink prior to v1.6.1 used an API that got removed in Sphinx 2.0, and Bookworm ships doxylink v1.5.1 and Sphinx v5.3.0, which makes me wonder how this got tested). The issue is fixed in Debian 13, and the doxylink module can be installed from PyPI in the meantime. Compared to v1, this series print a nicer error message when the doxylink module is not found, which should hopefully help end users troubleshooting the problem. I've posted a series to update the CI containers with the new dependency, see [1]. With those patches applied, this series passes CI. [1] https://patchwork.libcamera.org/project/libcamera/list/?series=5339. Laurent Pinchart (4): Documentation: Remove unneeded options from Sphinx configuration Documentation: Drop documentation author names Documentation: Use Sphinx doxylink to generate links to doxygen Documentation: Replace links to Doxygen documentation with doxylink Documentation/Doxyfile-internal.in | 2 + Documentation/Doxyfile-public.in | 2 + Documentation/conf.py | 95 +----- Documentation/environment_variables.rst | 2 +- .../guides/application-developer.rst | 30 +- Documentation/guides/pipeline-handler.rst | 312 +++++++----------- Documentation/libcamera_architecture.rst | 13 +- Documentation/meson.build | 50 +-- README.rst | 3 +- 9 files changed, 187 insertions(+), 322 deletions(-) base-commit: 2d5a1367e2b14dab9671270655bbb1702e0826de --- Regards, Laurent Pinchart