Patch Detail
Show a patch.
GET /api/patches/24034/?format=api
{ "id": 24034, "url": "https://patchwork.libcamera.org/api/patches/24034/?format=api", "web_url": "https://patchwork.libcamera.org/patch/24034/", "project": { "id": 1, "url": "https://patchwork.libcamera.org/api/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": "<20250729204228.23217-4-laurent.pinchart@ideasonboard.com>", "date": "2025-07-29T20:42:26", "name": "[v2,3/4] Documentation: Use Sphinx doxylink to generate links to doxygen", "commit_ref": null, "pull_url": null, "state": "superseded", "archived": false, "hash": "bb74ae34140b2e4cf6919a7c6d9b3ed428383c89", "submitter": { "id": 2, "url": "https://patchwork.libcamera.org/api/people/2/?format=api", "name": "Laurent Pinchart", "email": "laurent.pinchart@ideasonboard.com" }, "delegate": null, "mbox": "https://patchwork.libcamera.org/patch/24034/mbox/", "series": [ { "id": 5349, "url": "https://patchwork.libcamera.org/api/series/5349/?format=api", "web_url": "https://patchwork.libcamera.org/project/libcamera/list/?series=5349", "date": "2025-07-29T20:42:23", "name": "Documentation: Use doxylink to generate Sphinx-to-Doxygen links", "version": 2, "mbox": "https://patchwork.libcamera.org/series/5349/mbox/" } ], "comments": "https://patchwork.libcamera.org/api/patches/24034/comments/", "check": "pending", "checks": "https://patchwork.libcamera.org/api/patches/24034/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 40BFCBDC71\n\tfor <parsemail@patchwork.libcamera.org>;\n\tTue, 29 Jul 2025 20:42:49 +0000 (UTC)", "from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id E1F6A691FE;\n\tTue, 29 Jul 2025 22:42:48 +0200 (CEST)", "from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[213.167.242.64])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 10BA3691F7\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tTue, 29 Jul 2025 22:42:42 +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 088756DC\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tTue, 29 Jul 2025 22:41:58 +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=\"R7fVTek2\"; dkim-atps=neutral", "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1753821719;\n\tbh=Mf/jnCJHimW9mZILv98I0st41w3O9vIDETbRoDzncC0=;\n\th=From:To:Subject:Date:In-Reply-To:References:From;\n\tb=R7fVTek2KfAEu1LN78voKbH/o38TkEuwz8ulkP5FA4E677yUQW/je7d5xVpsbGnTo\n\teBb3lYszmzejIPyBqq7XIQLncAYaNTdPbyTnXvaUVuin8sIOu57SzzrsbS/NIFnpVi\n\tJGaqxaziZzFCjhDGJrY7xe1vfH5SevBVQHXQvPno=", "From": "Laurent Pinchart <laurent.pinchart@ideasonboard.com>", "To": "libcamera-devel@lists.libcamera.org", "Subject": "[PATCH v2 3/4] Documentation: Use Sphinx doxylink to generate links\n\tto doxygen", "Date": "Tue, 29 Jul 2025 23:42:26 +0300", "Message-ID": "<20250729204228.23217-4-laurent.pinchart@ideasonboard.com>", "X-Mailer": "git-send-email 2.49.1", "In-Reply-To": "<20250729204228.23217-1-laurent.pinchart@ideasonboard.com>", "References": "<20250729204228.23217-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 Sphinx documentation needs to link to the API\ndocumentation generated by Doxygen. The links currently point to the\ndocumentation hosted on the official https://libcamera.org/ website.\nThis causes multiple issues:\n\n- Doxygen generates URLs with MD5 hashes of function signatures, making\n the link targets unstable.\n\n- When testing documentation builds that include API changes, links to\n new API elements will be broken.\n\n- The generated documentation can't be browsed offline.\n\nFix this by using the Sphinx doxylink extension. This allows specifying\nlink targets as class and function names, with the link being\nautomatically generated using the same MD5 hashing as Doxygen. The root\nof the link target is configured in a central location, which defaults\nto the build directory and can be overridden to point to the libcamera\nwebsite when pushing the documentation.\n\nThis commit only introduces the infrastructure to use doxylink. Manual\nlinks will be replaced separately.\n\nSigned-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>\n---\nChanges since v1:\n\n- Add sphinxcontrib.doxylink to py_modules\n\npy_modules\n---\n Documentation/Doxyfile-internal.in | 2 ++\n Documentation/Doxyfile-public.in | 2 ++\n Documentation/conf.py | 13 +++++++-\n Documentation/meson.build | 50 +++++++++++++++++-------------\n README.rst | 3 +-\n 5 files changed, 46 insertions(+), 24 deletions(-)", "diff": "diff --git a/Documentation/Doxyfile-internal.in b/Documentation/Doxyfile-internal.in\nindex 5343bc2b131c..a422bb0719da 100644\n--- a/Documentation/Doxyfile-internal.in\n+++ b/Documentation/Doxyfile-internal.in\n@@ -3,6 +3,8 @@\n @INCLUDE_PATH = @TOP_BUILDDIR@/Documentation\n @INCLUDE = Doxyfile-common\n \n+GENERATE_TAGFILE = @TOP_BUILDDIR@/Documentation/internal-api-html/tagfile.xml\n+\n HIDE_UNDOC_CLASSES = NO\n HIDE_UNDOC_MEMBERS = NO\n HTML_OUTPUT = internal-api-html\ndiff --git a/Documentation/Doxyfile-public.in b/Documentation/Doxyfile-public.in\nindex 36bb57584a07..c3a8b0dd003a 100644\n--- a/Documentation/Doxyfile-public.in\n+++ b/Documentation/Doxyfile-public.in\n@@ -3,6 +3,8 @@\n @INCLUDE_PATH = @TOP_BUILDDIR@/Documentation\n @INCLUDE = Doxyfile-common\n \n+GENERATE_TAGFILE = @TOP_BUILDDIR@/Documentation/api-html/tagfile.xml\n+\n HIDE_UNDOC_CLASSES = YES\n HIDE_UNDOC_MEMBERS = YES\n HTML_OUTPUT = api-html\ndiff --git a/Documentation/conf.py b/Documentation/conf.py\nindex 870937289eb4..f50be60a1559 100644\n--- a/Documentation/conf.py\n+++ b/Documentation/conf.py\n@@ -37,7 +37,8 @@ author = 'The libcamera documentation authors'\n # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom\n # ones.\n extensions = [\n- 'sphinx.ext.graphviz'\n+ 'sphinx.ext.graphviz',\n+ 'sphinxcontrib.doxylink',\n ]\n \n graphviz_output_format = 'svg'\n@@ -71,6 +72,16 @@ exclude_patterns = [\n # The name of the Pygments (syntax highlighting) style to use.\n pygments_style = None\n \n+doxylink = {\n+ 'doxy-pub': (\n+ 'Documentation/api-html/tagfile.xml',\n+ '../api-html/',\n+ ),\n+ 'doxy-int': (\n+ 'Documentation/internal-api-html/tagfile.xml',\n+ '../internal-api-html/',\n+ ),\n+}\n \n # -- Options for HTML output -------------------------------------------------\n \ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex 3afdcc1a87af..77a14e591a90 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -81,16 +81,16 @@ if doxygen.found() and dot.found()\n '@INPUT@',\n ])\n \n- custom_target('doxygen-public',\n- input : [\n- doxyfile,\n- doxyfile_common,\n- ],\n- output : 'api-html',\n- command : [doxygen, doxyfile],\n- install : true,\n- install_dir : doc_install_dir,\n- install_tag : 'doc')\n+ doxygen_public = custom_target('doxygen-public',\n+ input : [\n+ doxyfile,\n+ doxyfile_common,\n+ ],\n+ output : 'api-html',\n+ command : [doxygen, doxyfile],\n+ install : true,\n+ install_dir : doc_install_dir,\n+ install_tag : 'doc')\n \n # This is the internal documentation, which hard-codes a list of directories\n # to parse in its doxyfile.\n@@ -99,18 +99,18 @@ if doxygen.found() and dot.found()\n output : 'Doxyfile-internal',\n configuration : cdata)\n \n- custom_target('doxygen-internal',\n- input : [\n- doxyfile,\n- doxyfile_common,\n- doxygen_public_input,\n- doxygen_internal_input,\n- ],\n- output : 'internal-api-html',\n- command : [doxygen, doxyfile],\n- install : true,\n- install_dir : doc_install_dir,\n- install_tag : 'doc-internal')\n+ doxygen_internal = custom_target('doxygen-internal',\n+ input : [\n+ doxyfile,\n+ doxyfile_common,\n+ doxygen_public_input,\n+ doxygen_internal_input,\n+ ],\n+ output : 'internal-api-html',\n+ command : [doxygen, doxyfile],\n+ install : true,\n+ install_dir : doc_install_dir,\n+ install_tag : 'doc-internal')\n endif\n \n #\n@@ -146,6 +146,8 @@ if sphinx.found()\n '../README.rst',\n ]\n \n+ py_modules += ['sphinxcontrib.doxylink']\n+\n release = 'release=v' + libcamera_git_version\n \n custom_target('documentation',\n@@ -154,6 +156,10 @@ if sphinx.found()\n input : docs_sources,\n output : 'html',\n build_by_default : true,\n+ depends : [\n+ doxygen_public,\n+ doxygen_internal,\n+ ],\n install : true,\n install_dir : doc_install_dir,\n install_tag : 'doc')\ndiff --git a/README.rst b/README.rst\nindex e2a6e275895e..e9a7dd82de74 100644\n--- a/README.rst\n+++ b/README.rst\n@@ -67,7 +67,8 @@ for device hotplug enumeration: [optional]\n libudev-dev\n \n for documentation: [optional]\n- python3-sphinx doxygen graphviz texlive-latex-extra\n+ doxygen graphviz python3-sphinx python3-sphinxcontrib.doxylink (>= 1.6.1)\n+ texlive-latex-extra\n \n for gstreamer: [optional]\n libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev\n", "prefixes": [ "v2", "3/4" ] }