From patchwork Wed Jul 30 11:50:41 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 24039 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 98995BDCC1 for ; Wed, 30 Jul 2025 11:50:56 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 69BB8691FB; Wed, 30 Jul 2025 13:50:55 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="vttxHStY"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [213.167.242.64]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id E8B02691F6 for ; Wed, 30 Jul 2025 13:50:53 +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 4E1BDA57 for ; Wed, 30 Jul 2025 13:50:10 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1753876210; bh=bCMszYlVepVYGZ10PurZqJPQst+OiemEL9e1wJ/YtSg=; h=From:To:Subject:Date:From; b=vttxHStYquC0T+6DKFdKIWokPFqYlxnPqkr7EkVEatwkRUyFhLVPcFHoHJCeea19+ IxW+5C+kjD39FVQDUXF2Q8poF2nfhQuJ/G1CyhkqJzGZqPv8p/lcLm3g3dhrwFVnM6 mkPi18lHSwGmfCIQpSUt61blHzcmZuWHg5svkfKY= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Subject: [PATCH v3 0/3] Documentation: Use doxylink to generate Sphinx-to-Doxygen links Date: Wed, 30 Jul 2025 14:50:41 +0300 Message-ID: <20250730115045.3481-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 v2, this series print an even nicer error message when the doxylink module is not found or is too old, 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 (3): Documentation: Remove unneeded options from Sphinx configuration Documentation: Drop documentation author names Documentation: Use Sphinx doxylink to generate links to doxygen Documentation/Doxyfile-internal.in | 2 + Documentation/Doxyfile-public.in | 2 + Documentation/conf.py | 95 +++++------------------------- Documentation/meson.build | 69 +++++++++++++++------- README.rst | 3 +- 5 files changed, 67 insertions(+), 104 deletions(-) base-commit: 2d5a1367e2b14dab9671270655bbb1702e0826de prerequisite-patch-id: 91704d112366f8370ab1cf4e34f4a1ab9471e352 --- Regards, Laurent Pinchart