Patch Detail
Show a patch.
GET /api/1.1/patches/20825/?format=api
{ "id": 20825, "url": "https://patchwork.libcamera.org/api/1.1/patches/20825/?format=api", "web_url": "https://patchwork.libcamera.org/patch/20825/", "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": "<20240807154410.9552-4-laurent.pinchart@ideasonboard.com>", "date": "2024-08-07T15:44:08", "name": "[v6,3/5] Documentation: Split public/private documentation", "commit_ref": null, "pull_url": null, "state": "accepted", "archived": false, "hash": "c3984740b07859bc4cb8188e9c756eadb403376c", "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/20825/mbox/", "series": [ { "id": 4497, "url": "https://patchwork.libcamera.org/api/1.1/series/4497/?format=api", "web_url": "https://patchwork.libcamera.org/project/libcamera/list/?series=4497", "date": "2024-08-07T15:44:05", "name": "Split libcamera documentation in public and internal APIs", "version": 6, "mbox": "https://patchwork.libcamera.org/series/4497/mbox/" } ], "comments": "https://patchwork.libcamera.org/api/patches/20825/comments/", "check": "pending", "checks": "https://patchwork.libcamera.org/api/patches/20825/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 431ACC323E\n\tfor <parsemail@patchwork.libcamera.org>;\n\tWed, 7 Aug 2024 15:44:42 +0000 (UTC)", "from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 034EA633BA;\n\tWed, 7 Aug 2024 17:44:42 +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 940C9633B4\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tWed, 7 Aug 2024 17:44:37 +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 ESMTPSA id 962A16AF;\n\tWed, 7 Aug 2024 17:43:44 +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=\"J3fhogfe\"; dkim-atps=neutral", "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1723045424;\n\tbh=1e2xS2Vz82SAbaRCpKPNmXCkQoVtnK0YgMwwTSZwrQk=;\n\th=From:To:Cc:Subject:Date:In-Reply-To:References:From;\n\tb=J3fhogfewbHDRzrALkiI6J++UT+kqFmcmnt/s0H6/fiwE2EXn1wXEa5Yvl4YeW2iC\n\tZ7yxlnvmQpgagERFQZbZXzJhBp7rNgJP7KLOp5GIgH30NQoetOlxmyPKO0b0/UlRkk\n\t4gFhFAuVSRkM90K3DwtBQONmO95oNJ/LRrnxefz8=", "From": "Laurent Pinchart <laurent.pinchart@ideasonboard.com>", "To": "libcamera-devel@lists.libcamera.org", "Cc": "Daniel Scally <dan.scally@ideasonboard.com>", "Subject": "[PATCH v6 3/5] Documentation: Split public/private documentation", "Date": "Wed, 7 Aug 2024 18:44:08 +0300", "Message-ID": "<20240807154410.9552-4-laurent.pinchart@ideasonboard.com>", "X-Mailer": "git-send-email 2.44.2", "In-Reply-To": "<20240807154410.9552-1-laurent.pinchart@ideasonboard.com>", "References": "<20240807154410.9552-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": "From: Daniel Scally <dan.scally@ideasonboard.com>\n\nThe API reference pages generated by Doxygen are comprehensive, but\ntherefore quite overwhelming for application developers who will\nlikely never need to use the majority of the library's objects. To\nreduce the complexity of the documentation, split it into two runs of\ndoxygen.\n\nThe first run of doxygen is for the public API. We pass a specific list\nof source files to parse, which is built from the arrays of public\nheaders and sources in meson build files. This ensures that we only\ngenerate the documentation for code from those files.\n\nA custom Python script is needed to add the list of input files to\nDoxyfile, as several of the objects included in the header and source\narray are custom_tgt objects, which can't be handled as strings to\npopulate a variable in the configuration data.\n\nThe headers defining the Extensible and Object classes (class.h and\nobject.h respectively), as well as the corresponding source files, are\nexcluded from the public API documentation despite being referenced in\nthe meson public headers and sources arrays. This is due to the fact\nthat public API classes inherit from Extensible and Object, making the\nExtensible and Object classes part of the public ABI. Those two base\nclasses are however implementation details and must not be accessed\ndirectly by application code.\n\nThe second run of doxygen is for the internal API. This contains\ndocumentation for all of the library's objects as it currently does.\nThis set will now be output into build/Documentation/internal-api-html.\n\nSigned-off-by: Daniel Scally <dan.scally@ideasonboard.com>\nCo-developed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>\nSigned-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>\nReviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>\nReviewed-by: Daniel Scally <dan.scally@ideasonboard.com>\n---\nChanges since v5:\n\n- Reword and fix comments documenting the doxygen process\n- Drop the gen-doxyfile.py step for the internal doc\n- Drop unneeded comment\n- Add blank line\n---\n .../{Doxyfile.in => Doxyfile-common.in} | 24 --------\n Documentation/Doxyfile-internal.in | 30 +++++++++\n Documentation/Doxyfile-public.in | 20 ++++++\n Documentation/gen-doxyfile.py | 46 ++++++++++++++\n Documentation/meson.build | 61 +++++++++++++++++--\n 5 files changed, 151 insertions(+), 30 deletions(-)\n rename Documentation/{Doxyfile.in => Doxyfile-common.in} (62%)\n create mode 100644 Documentation/Doxyfile-internal.in\n create mode 100644 Documentation/Doxyfile-public.in\n create mode 100755 Documentation/gen-doxyfile.py", "diff": "diff --git a/Documentation/Doxyfile.in b/Documentation/Doxyfile-common.in\nsimilarity index 62%\nrename from Documentation/Doxyfile.in\nrename to Documentation/Doxyfile-common.in\nindex 6e5a3830ec38..a70aee430e77 100644\n--- a/Documentation/Doxyfile.in\n+++ b/Documentation/Doxyfile-common.in\n@@ -17,20 +17,11 @@ EXTENSION_MAPPING = h=C++\n \n TOC_INCLUDE_HEADINGS = 0\n \n-INTERNAL_DOCS = YES\n CASE_SENSE_NAMES = YES\n \n QUIET = YES\n WARN_AS_ERROR = @WARN_AS_ERROR@\n \n-INPUT = \"@TOP_SRCDIR@/Documentation\" \\\n- \"@TOP_SRCDIR@/include/libcamera\" \\\n- \"@TOP_SRCDIR@/src/ipa/ipu3\" \\\n- \"@TOP_SRCDIR@/src/ipa/libipa\" \\\n- \"@TOP_SRCDIR@/src/libcamera\" \\\n- \"@TOP_BUILDDIR@/include/libcamera\" \\\n- \"@TOP_BUILDDIR@/src/libcamera\"\n-\n FILE_PATTERNS = *.c \\\n *.cpp \\\n *.dox \\\n@@ -38,19 +29,6 @@ FILE_PATTERNS = *.c \\\n \n RECURSIVE = YES\n \n-EXCLUDE = @TOP_SRCDIR@/include/libcamera/base/span.h \\\n- @TOP_SRCDIR@/include/libcamera/internal/device_enumerator_sysfs.h \\\n- @TOP_SRCDIR@/include/libcamera/internal/device_enumerator_udev.h \\\n- @TOP_SRCDIR@/include/libcamera/internal/ipc_pipe_unixsocket.h \\\n- @TOP_SRCDIR@/src/libcamera/device_enumerator_sysfs.cpp \\\n- @TOP_SRCDIR@/src/libcamera/device_enumerator_udev.cpp \\\n- @TOP_SRCDIR@/src/libcamera/ipc_pipe_unixsocket.cpp \\\n- @TOP_SRCDIR@/src/libcamera/pipeline/ \\\n- @TOP_SRCDIR@/src/libcamera/tracepoints.cpp \\\n- @TOP_BUILDDIR@/include/libcamera/internal/tracepoints.h \\\n- @TOP_BUILDDIR@/include/libcamera/ipa/soft_ipa_interface.h \\\n- @TOP_BUILDDIR@/src/libcamera/proxy/\n-\n EXCLUDE_PATTERNS = @TOP_BUILDDIR@/include/libcamera/ipa/*_serializer.h \\\n @TOP_BUILDDIR@/include/libcamera/ipa/*_proxy.h \\\n @TOP_BUILDDIR@/include/libcamera/ipa/ipu3_*.h \\\n@@ -73,8 +51,6 @@ EXCLUDE_SYMBOLS = libcamera::BoundMethodArgs \\\n \n EXCLUDE_SYMLINKS = YES\n \n-HTML_OUTPUT = api-html\n-\n GENERATE_LATEX = NO\n \n MACRO_EXPANSION = YES\ndiff --git a/Documentation/Doxyfile-internal.in b/Documentation/Doxyfile-internal.in\nnew file mode 100644\nindex 000000000000..5e0310091416\n--- /dev/null\n+++ b/Documentation/Doxyfile-internal.in\n@@ -0,0 +1,30 @@\n+# SPDX-License-Identifier: CC-BY-SA-4.0\n+\n+@INCLUDE_PATH = @TOP_BUILDDIR@/Documentation\n+@INCLUDE = Doxyfile-common\n+\n+HIDE_UNDOC_CLASSES = NO\n+HIDE_UNDOC_MEMBERS = NO\n+HTML_OUTPUT = internal-api-html\n+INTERNAL_DOCS = YES\n+\n+INPUT = \"@TOP_SRCDIR@/Documentation\" \\\n+ \"@TOP_SRCDIR@/include/libcamera\" \\\n+ \"@TOP_SRCDIR@/src/ipa/ipu3\" \\\n+ \"@TOP_SRCDIR@/src/ipa/libipa\" \\\n+ \"@TOP_SRCDIR@/src/libcamera\" \\\n+ \"@TOP_BUILDDIR@/include/libcamera\" \\\n+ \"@TOP_BUILDDIR@/src/libcamera\"\n+\n+EXCLUDE = @TOP_SRCDIR@/include/libcamera/base/span.h \\\n+ @TOP_SRCDIR@/include/libcamera/internal/device_enumerator_sysfs.h \\\n+ @TOP_SRCDIR@/include/libcamera/internal/device_enumerator_udev.h \\\n+ @TOP_SRCDIR@/include/libcamera/internal/ipc_pipe_unixsocket.h \\\n+ @TOP_SRCDIR@/src/libcamera/device_enumerator_sysfs.cpp \\\n+ @TOP_SRCDIR@/src/libcamera/device_enumerator_udev.cpp \\\n+ @TOP_SRCDIR@/src/libcamera/ipc_pipe_unixsocket.cpp \\\n+ @TOP_SRCDIR@/src/libcamera/pipeline/ \\\n+ @TOP_SRCDIR@/src/libcamera/tracepoints.cpp \\\n+ @TOP_BUILDDIR@/include/libcamera/internal/tracepoints.h \\\n+ @TOP_BUILDDIR@/include/libcamera/ipa/soft_ipa_interface.h \\\n+ @TOP_BUILDDIR@/src/libcamera/proxy/\ndiff --git a/Documentation/Doxyfile-public.in b/Documentation/Doxyfile-public.in\nnew file mode 100644\nindex 000000000000..36bb57584a07\n--- /dev/null\n+++ b/Documentation/Doxyfile-public.in\n@@ -0,0 +1,20 @@\n+# SPDX-License-Identifier: CC-BY-SA-4.0\n+\n+@INCLUDE_PATH = @TOP_BUILDDIR@/Documentation\n+@INCLUDE = Doxyfile-common\n+\n+HIDE_UNDOC_CLASSES = YES\n+HIDE_UNDOC_MEMBERS = YES\n+HTML_OUTPUT = api-html\n+INTERNAL_DOCS = NO\n+\n+INPUT = \"@TOP_SRCDIR@/Documentation\" \\\n+ ${inputs}\n+\n+EXCLUDE = @TOP_SRCDIR@/include/libcamera/base/class.h \\\n+ @TOP_SRCDIR@/include/libcamera/base/object.h \\\n+ @TOP_SRCDIR@/include/libcamera/base/span.h \\\n+ @TOP_SRCDIR@/src/libcamera/base/class.cpp \\\n+ @TOP_SRCDIR@/src/libcamera/base/object.cpp\n+\n+PREDEFINED += __DOXYGEN_PUBLIC__\ndiff --git a/Documentation/gen-doxyfile.py b/Documentation/gen-doxyfile.py\nnew file mode 100755\nindex 000000000000..c265bc2f3fc4\n--- /dev/null\n+++ b/Documentation/gen-doxyfile.py\n@@ -0,0 +1,46 @@\n+#!/usr/bin/env python3\n+# SPDX-License-Identifier: GPL-2.0-or-later\n+# Copyright (C) 2024, Google Inc.\n+#\n+# Author: Laurent Pinchart <laurent.pinchart@ideasonboard.com>\n+#\n+# Generate Doxyfile from a template\n+\n+import argparse\n+import os\n+import string\n+import sys\n+\n+\n+def fill_template(template, data):\n+\n+ template = open(template, 'rb').read()\n+ template = template.decode('utf-8')\n+ template = string.Template(template)\n+\n+ return template.substitute(data)\n+\n+\n+def main(argv):\n+\n+ parser = argparse.ArgumentParser()\n+ parser.add_argument('-o', dest='output', metavar='file',\n+ type=argparse.FileType('w', encoding='utf-8'),\n+ default=sys.stdout,\n+ help='Output file name (default: standard output)')\n+ parser.add_argument('template', metavar='doxyfile.tmpl', type=str,\n+ help='Doxyfile template')\n+ parser.add_argument('inputs', type=str, nargs='*',\n+ help='Input files')\n+\n+ args = parser.parse_args(argv[1:])\n+\n+ inputs = [f'\"{os.path.realpath(input)}\"' for input in args.inputs]\n+ data = fill_template(args.template, {'inputs': (' \\\\\\n' + ' ' * 25).join(inputs)})\n+ args.output.write(data)\n+\n+ return 0\n+\n+\n+if __name__ == '__main__':\n+ sys.exit(main(sys.argv))\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex 1d84ed815b50..1ba40fdf67ac 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -24,9 +24,9 @@ if doxygen.found() and dot.found()\n \n cdata.set('PREDEFINED', ' \\\\\\n\\t\\t\\t '.join(doxygen_predefined))\n \n- doxyfile = configure_file(input : 'Doxyfile.in',\n- output : 'Doxyfile',\n- configuration : cdata)\n+ doxyfile_common = configure_file(input : 'Doxyfile-common.in',\n+ output : 'Doxyfile-common',\n+ configuration : cdata)\n \n doxygen_public_input = [\n libcamera_base_public_headers,\n@@ -50,17 +50,66 @@ if doxygen.found() and dot.found()\n doxygen_internal_input += [ipu3_ipa_sources]\n endif\n \n- custom_target('doxygen',\n+ # We run doxygen twice - the first run excludes internal API objects as it\n+ # is intended to document the public API only. A second run covers all of\n+ # the library's objects for libcamera developers. Common configuration is\n+ # set in an initially generated Doxyfile, which is then included by the two\n+ # final Doxyfiles.\n+\n+ # This is the \"public\" run of doxygen generating an abridged version of the\n+ # API's documentation.\n+\n+ doxyfile_tmpl = configure_file(input : 'Doxyfile-public.in',\n+ output : 'Doxyfile-public.tmpl',\n+ configuration : cdata)\n+\n+ # The set of public input files stored in the doxygen_public_input array\n+ # needs to be set in Doxyfile public. We can't pass them through cdata\n+ # cdata, as some of the array members are custom_tgt instances, which\n+ # configuration_data.set() doesn't support. Using a separate script invoked\n+ # through custom_target(), which supports custom_tgt instances as inputs.\n+\n+ doxyfile = custom_target('doxyfile-public',\n+ input : [\n+ doxygen_public_input,\n+ ],\n+ output : 'Doxyfile-public',\n+ command : [\n+ 'gen-doxyfile.py',\n+ '-o', '@OUTPUT@',\n+ doxyfile_tmpl,\n+ '@INPUT@',\n+ ])\n+\n+ custom_target('doxygen-public',\n input : [\n doxyfile,\n- doxygen_public_input,\n- doxygen_internal_input,\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+\n+ doxyfile = configure_file(input : 'Doxyfile-internal.in',\n+ output : 'Doxyfile-internal',\n+ configuration : cdata)\n+\n+ custom_target('doxygen-internal',\n+ input : [\n+ doxyfile,\n+ doxyfile_common,\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", "prefixes": [ "v6", "3/5" ] }