Patch Detail
Show a patch.
GET /api/1.1/patches/24385/?format=api
{ "id": 24385, "url": "https://patchwork.libcamera.org/api/1.1/patches/24385/?format=api", "web_url": "https://patchwork.libcamera.org/patch/24385/", "project": { "id": 1, "url": "https://patchwork.libcamera.org/api/1.1/projects/1/?format=api", "name": "libcamera", "link_name": "libcamera", "list_id": "libcamera_core", "list_email": "libcamera-devel@lists.libcamera.org", "web_url": "", "scm_url": "", "webscm_url": "" }, "msgid": "<20250917201742.16406-8-laurent.pinchart@ideasonboard.com>", "date": "2025-09-17T20:17:38", "name": "[v3,07/10] Documentation: Improve Sphinx and Doxygen integration", "commit_ref": null, "pull_url": null, "state": "accepted", "archived": false, "hash": "65c77a9b2a74af978c4a8f747e68d49f0168a2a5", "submitter": { "id": 2, "url": "https://patchwork.libcamera.org/api/1.1/people/2/?format=api", "name": "Laurent Pinchart", "email": "laurent.pinchart@ideasonboard.com" }, "delegate": null, "mbox": "https://patchwork.libcamera.org/patch/24385/mbox/", "series": [ { "id": 5448, "url": "https://patchwork.libcamera.org/api/1.1/series/5448/?format=api", "web_url": "https://patchwork.libcamera.org/project/libcamera/list/?series=5448", "date": "2025-09-17T20:17:31", "name": "Documentation theming update", "version": 3, "mbox": "https://patchwork.libcamera.org/series/5448/mbox/" } ], "comments": "https://patchwork.libcamera.org/api/patches/24385/comments/", "check": "pending", "checks": "https://patchwork.libcamera.org/api/patches/24385/checks/", "tags": {}, "headers": { "Return-Path": "<libcamera-devel-bounces@lists.libcamera.org>", "X-Original-To": "parsemail@patchwork.libcamera.org", "Delivered-To": "parsemail@patchwork.libcamera.org", "Received": [ "from lancelot.ideasonboard.com (lancelot.ideasonboard.com\n\t[92.243.16.209])\n\tby patchwork.libcamera.org (Postfix) with ESMTPS id E5E3BC328C\n\tfor <parsemail@patchwork.libcamera.org>;\n\tWed, 17 Sep 2025 20:18:33 +0000 (UTC)", "from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id D63AA69382;\n\tWed, 17 Sep 2025 22:18:32 +0200 (CEST)", "from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 97CA069379\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tWed, 17 Sep 2025 22:18:23 +0200 (CEST)", "from pendragon.ideasonboard.com (81-175-209-231.bb.dnainternet.fi\n\t[81.175.209.231])\n\tby perceval.ideasonboard.com (Postfix) with UTF8SMTPSA id 7259F6A8\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tWed, 17 Sep 2025 22:17:04 +0200 (CEST)" ], "Authentication-Results": "lancelot.ideasonboard.com; dkim=pass (1024-bit key;\n\tunprotected) header.d=ideasonboard.com header.i=@ideasonboard.com\n\theader.b=\"iIAwUDKX\"; dkim-atps=neutral", "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1758140224;\n\tbh=N376aSK3qfu1wiTEhislzcSsHMcg6yFxbo6+C/X4bHo=;\n\th=From:To:Subject:Date:In-Reply-To:References:From;\n\tb=iIAwUDKXiuXWZyysQYiS9vDXl8LseyomQanpr3nT7jo1suLFxfIl7vDvxyzWY/O/C\n\t0EceE33MPJ86zYKYxPrcT2rBoXoT4Kbh6tRf8oNN7Xe4+gApZCnl1PWOKF4g0VYVhf\n\twpWPQzvV857Tzz1f7tCWHPseFH+pCJRYDakg4Z3U=", "From": "Laurent Pinchart <laurent.pinchart@ideasonboard.com>", "To": "libcamera-devel@lists.libcamera.org", "Subject": "[PATCH v3 07/10] Documentation: Improve Sphinx and Doxygen\n\tintegration", "Date": "Wed, 17 Sep 2025 23:17:38 +0300", "Message-ID": "<20250917201742.16406-8-laurent.pinchart@ideasonboard.com>", "X-Mailer": "git-send-email 2.49.1", "In-Reply-To": "<20250917201742.16406-1-laurent.pinchart@ideasonboard.com>", "References": "<20250917201742.16406-1-laurent.pinchart@ideasonboard.com>", "MIME-Version": "1.0", "Content-Transfer-Encoding": "8bit", "X-BeenThere": "libcamera-devel@lists.libcamera.org", "X-Mailman-Version": "2.1.29", "Precedence": "list", "List-Id": "<libcamera-devel.lists.libcamera.org>", "List-Unsubscribe": "<https://lists.libcamera.org/options/libcamera-devel>,\n\t<mailto:libcamera-devel-request@lists.libcamera.org?subject=unsubscribe>", "List-Archive": "<https://lists.libcamera.org/pipermail/libcamera-devel/>", "List-Post": "<mailto:libcamera-devel@lists.libcamera.org>", "List-Help": "<mailto:libcamera-devel-request@lists.libcamera.org?subject=help>", "List-Subscribe": "<https://lists.libcamera.org/listinfo/libcamera-devel>,\n\t<mailto:libcamera-devel-request@lists.libcamera.org?subject=subscribe>", "Errors-To": "libcamera-devel-bounces@lists.libcamera.org", "Sender": "\"libcamera-devel\" <libcamera-devel-bounces@lists.libcamera.org>" }, "content": "The libcamera documentation comprises two parts: pages generated by\nSphinx into the Documentation/html/ directory within the build tree, and\nAPI reference documentation generated by Doxygen into\nDocumentation/internal-api-html/ and Documentation/api-html/. The two\nparts are generated separately, but link to each other.\n\nFrom Sphinx to Doxygen, we use the doxylink extension for Sphinx to\ngenerate links to the Doxygen pages corresponding to API elements. The\nextension needs to be configured with the paths to the Doxygen\ndocumentation, which are set based on the html/, api-html/ and\ninternal-api-html/ directories being placed side by side in the same\nparent directory.\n\nFurthermore, we also want to link to the API documentation from the\nSphinx toctree. As toctrees can only link to pages within the Sphinx\ndocuments tree (or to http URLs), we have placeholder .rst documents for\napi-html and internal-api-html in the Sphinx documentation tree. Those\ngenerate the Documentation/html/internal-api-html/index.html and\nDocumentation/html/api-html/index.html placeholder files in the build\ntree.\n\nThe other way around, the API documentation's introduction pagelinks to\nSphinx pages using relative paths. Those paths are hardcoded based on\nthe api-html/ and internal-api-html/ directories being children of the\nhtml/ directory.\n\nThis results in links being broken in different ways in the build tree,\nas well as in the installation directory: the toctree links direct to\nthe placeholder pages within the html/ directory instead of the Doxygen\ndocumentation in sibling directories, and the Doxygen introduction links\nto Sphinx are simply broken. When publishing documentation on the\nwebsite we work around those issues by patching several files and moving\nthe api-html/ and internal-api-html/ directories to the html/ directory.\n\nFixing this is surprisingly difficult. The toctree links can't be\nchanged to point to a path outside of the Sphinx document tree as this\nisn't supported by Sphinx. Using http URLs would link to the\nlibcamera.org website inside of local documentation, which isn't\nacceptable. It may be possible to develop a Sphinx extension to patch\nthe toctree after it gets parsed, but that would be complex and likely\nfragile. Modifying the install path of the Doxygen documentation to\nhtml/api-html/ and html/internal-api-html/ causes issues as the Sphinx\ndocumentation will then overwrite the Doxygen index.html files with the\nplaceholder indexes. Creating symlinks from html/api-html/ to api-html/\nin the installation directory causes similar problems if 'meson install'\nis run twice. Creating the symlinks in the build directory (which was\nattempted with a custom Sphinx extension) is also a no-go: starting with\nmeson v1.8.0, installing symlinks to directories causes an exception due\nto a bug in meson.\n\nThe right solution is probably to investigate usage of the doxysphinx\nextension. As that's no small amount of work, let's start with a\nnon-perfect but simple improvement: configure doxylink based on the\napi-html/ and internal-api-html/ directories being children of the\nSphinx html/ documentation, and move those two API documentation\ndirectories to html/ during installation with a post-install script.\nThis fixes links in the installation directory. Links in the build\ndirectory remain broken, but that is not a regression.\n\nSigned-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>\n---\n Documentation/conf.py.in | 4 ++--\n Documentation/install-doxygen.sh | 18 ++++++++++++++++++\n Documentation/meson.build | 3 +++\n 3 files changed, 23 insertions(+), 2 deletions(-)\n create mode 100755 Documentation/install-doxygen.sh", "diff": "diff --git a/Documentation/conf.py.in b/Documentation/conf.py.in\nindex 34fa3956f49e..2c75a75799e6 100644\n--- a/Documentation/conf.py.in\n+++ b/Documentation/conf.py.in\n@@ -75,11 +75,11 @@ pygments_style = None\n doxylink = {\n 'doxy-pub': (\n '@TOP_BUILDDIR@/Documentation/api-html/tagfile.xml',\n- '../api-html/',\n+ 'api-html/',\n ),\n 'doxy-int': (\n '@TOP_BUILDDIR@/Documentation/internal-api-html/tagfile.xml',\n- '../internal-api-html/',\n+ 'internal-api-html/',\n ),\n }\n \ndiff --git a/Documentation/install-doxygen.sh b/Documentation/install-doxygen.sh\nnew file mode 100755\nindex 000000000000..ea5a19dc8fda\n--- /dev/null\n+++ b/Documentation/install-doxygen.sh\n@@ -0,0 +1,18 @@\n+#!/bin/sh\n+# SPDX-License-Identifier: GPL-2.0-or-later\n+# Copyright (C) 2025, Ideas on Board Oy\n+#\n+# Author: Laurent Pinchart <laurent.pinchart@ideasonboard.com>\n+#\n+# Move Doxygen-generated API documentation to correct location\n+\n+doc_dir=\"${MESON_INSTALL_DESTDIR_PREFIX}/$1\"\n+shift\n+dirs=\"$*\"\n+\n+echo \"Moving API documentation\"\n+\n+for dir in $dirs ; do\n+\trm -r \"${doc_dir}/html/${dir}\"\n+\tmv \"${doc_dir}/${dir}\" \"${doc_dir}/html/\"\n+done\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex 8cf7775902f3..022770968fcf 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -193,6 +193,9 @@ if sphinx.found()\n install_dir : doc_install_dir,\n install_tag : 'doc')\n \n+ meson.add_install_script('install-doxygen.sh', doc_install_dir,\n+ 'api-html', 'internal-api-html')\n+\n custom_target('documentation-linkcheck',\n command : [sphinx, '-W', '-b', 'linkcheck',\n '-c', sphinx_conf_dir,\n", "prefixes": [ "v3", "07/10" ] }