[{"id":35280,"web_url":"https://patchwork.libcamera.org/comment/35280/","msgid":"<20250804232459.GB31914@pendragon.ideasonboard.com>","date":"2025-08-04T23:24:59","subject":"Re: [RFC PATCH v1] Documentation: Fix documentation generation when\n\tsubproject","submitter":{"id":2,"url":"https://patchwork.libcamera.org/api/people/2/","name":"Laurent Pinchart","email":"laurent.pinchart@ideasonboard.com"},"content":"Hi Barnabás,\n\nThank you for the patch.\n\nOn Thu, Jul 31, 2025 at 02:32:47PM +0200, Barnabás Pőcze wrote:\n> The paths of the doxygen tag files for sphinxcontrib-doxygen must be\n> absolute or relative the the current working directory. However, when\n> libcamera is built as a subproject, the current working directory\n> is the top-level build directory. Thus the paths for the tag files\n> will not be correct.\n> \n> Fix that by using `configure_file()` to generate the final sphinx\n> configuration with the appropriate paths queried from meson.\n> \n> Signed-off-by: Barnabás Pőcze \n> ---\n> Documentation/{conf.py => conf.py.in} | 6 +++---\n> Documentation/meson.build | 16 ++++++++++++++--\n> 2 files changed, 17 insertions(+), 5 deletions(-)\n> rename Documentation/{conf.py => conf.py.in} (95%)\n> \n> diff --git a/Documentation/conf.py b/Documentation/conf.py.in\n> similarity index 95%\n> rename from Documentation/conf.py\n> rename to Documentation/conf.py.in\n> index f50be60a1..097e579b5 100644\n> --- a/Documentation/conf.py\n> +++ b/Documentation/conf.py.in\n> @@ -74,11 +74,11 @@ pygments_style = None\n> \n> doxylink = {\n> 'doxy-pub': (\n> - 'Documentation/api-html/tagfile.xml',\n> + '@TOP_BUILDDIR@/Documentation/api-html/tagfile.xml',\n> '../api-html/',\n> ),\n> 'doxy-int': (\n> - 'Documentation/internal-api-html/tagfile.xml',\n> + '@TOP_BUILDDIR@/Documentation/internal-api-html/tagfile.xml',\n> '../internal-api-html/',\n> ),\n> }\n\nI was hoping we could override this on the command line with Sphinx's -D\noption, using something like\n\ndoxylink = {\n 'doxy-pub': (\n f'{top_builddir}Documentation/api-html/tagfile.xml',\n '../api-html/',\n ),\n 'doxy-int': (\n f'{top_builddir}Documentation/internal-api-html/tagfile.xml',\n '../internal-api-html/',\n ),\n}\n\nand setting -D top_builddir=... but Sphinx apparently restricts -D to\noverride known config options, not arbitrary variables :-(\n\n> @@ -89,7 +89,7 @@ doxylink = {\n> # a list of builtin themes.\n> #\n> html_theme = 'theme'\n> -html_theme_path = ['.']\n> +html_theme_path = ['@THEME_DIR@']\n> \n> # Theme options are theme-specific and customize the look and feel of a theme\n> # further. For a list of options available for each theme, see the\n> diff --git a/Documentation/meson.build b/Documentation/meson.build\n> index b898ba3a0..0710084fe 100644\n> --- a/Documentation/meson.build\n> +++ b/Documentation/meson.build\n> @@ -142,11 +142,20 @@ if sphinx.found()\n> .format(mod, version, min_version))\n> endif\n> \n> + sphinx_conf = configure_file(input : 'conf.py.in',\n> + output : 'conf.py',\n> + configuration : {\n> + 'TOP_BUILDDIR': meson.project_build_root(),\n> + 'THEME_DIR': meson.current_source_dir(),\n\nAlphabetical order ?\n\n> + })\n> +\n> + sphinx_conf_dir = fs.parent(sphinx_conf)\n\nPlease import the fs module here. It's imported in\nsrc/gstreamer/meson.build, and I'd rather not rely on that here.\n\n> +\n> docs_sources = [\n> 'camera-sensor-model.rst',\n> 'code-of-conduct.rst',\n> 'coding-style.rst',\n> - 'conf.py',\n> + sphinx_conf,\n> 'contributing.rst',\n> 'design/ae.rst',\n> 'documentation-contents.rst',\n> @@ -171,6 +180,7 @@ if sphinx.found()\n> \n> custom_target('documentation',\n> command : [sphinx, '-D', release, '-q', '-W', '-b', 'html',\n> + '--conf-dir', sphinx_conf_dir,\n> meson.current_source_dir(), '@OUTPUT@'],\n> input : docs_sources,\n> output : 'html',\n> @@ -184,7 +194,9 @@ if sphinx.found()\n> install_tag : 'doc')\n> \n> custom_target('documentation-linkcheck',\n> - command : [sphinx, '-W', '-b', 'linkcheck', meson.current_source_dir(), '@OUTPUT@'],\n> + command : [sphinx, '-W', '-b', 'linkcheck',\n> + '--conf-dir', sphinx_conf_dir,\n> + meson.current_source_dir(), '@OUTPUT@'],\n\nlinkcheck will also benefit from overriding paths in doxylink (see my\nseparate e-mail on that subject), so this patch comes handy.\n\nWith the above comments addressed,\n\nReviewed-by: Laurent Pinchart \n\n> build_always_stale : true,\n> input : docs_sources,\n> output : 'linkcheck')","headers":{"Return-Path":"","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 18860BDCC1\n\tfor ;\n\tMon, 4 Aug 2025 23:25:16 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 353D26921E;\n\tTue, 5 Aug 2025 01:25:15 +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 A9A1661466\n\tfor ;\n\tTue, 5 Aug 2025 01:25:13 +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 EF41F32FD; \n\tTue, 5 Aug 2025 01:24:25 +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=\"P6LJf+z5\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1754349866;\n\tbh=yXYe0fy8icuw5gziVHTyrhMpJLc5McFST/GFxFJEoKM=;\n\th=Date:From:To:Cc:Subject:References:In-Reply-To:From;\n\tb=P6LJf+z51jpkrJ/vBhLIwQ1xjQceB+sdbfUVfIyVP68FtM4JAhuz6PS7r8ffq0kFK\n\tPKC4/6Au01pu2ecwjYDFpcX/65WYU94dNvzPSrSx0RQKenAPDZjxeqvW9PWsJizP9h\n\tc8svzFZGg3zNr6kOKfGeS5D9lxXBE7AjkU2M1iHk=","Date":"Tue, 5 Aug 2025 02:24:59 +0300","From":"Laurent Pinchart ","To":"=?utf-8?q?Barnab=C3=A1s_P=C5=91cze?= ","Cc":"libcamera-devel@lists.libcamera.org","Subject":"Re: [RFC PATCH v1] Documentation: Fix documentation generation when\n\tsubproject","Message-ID":"<20250804232459.GB31914@pendragon.ideasonboard.com>","References":"<20250731123247.755475-1-barnabas.pocze@ideasonboard.com>","MIME-Version":"1.0","Content-Type":"text/plain; charset=utf-8","Content-Disposition":"inline","Content-Transfer-Encoding":"8bit","In-Reply-To":"<20250731123247.755475-1-barnabas.pocze@ideasonboard.com>","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.29","Precedence":"list","List-Id":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" "}}]