[{"id":35769,"web_url":"https://patchwork.libcamera.org/comment/35769/","msgid":"<20250910172621.GH20904@pendragon.ideasonboard.com>","date":"2025-09-10T17:26:21","subject":"Re: [PATCH 4/6] documentation: Include API docs in the sphinx\n\tdocumentation","submitter":{"id":2,"url":"https://patchwork.libcamera.org/api/people/2/","name":"Laurent Pinchart","email":"laurent.pinchart@ideasonboard.com"},"content":"On Mon, Sep 08, 2025 at 04:07:47PM +0200, Stefan Klug wrote:\n> This commit prepares the move of all the libcamera documetation to a\n\ns/documetation/documentation/\n\n> place separate from the website. This makes it easier to handle website\n> and docs separately.\n> \n> The index is updated to mimic the structure currently available on the\n> website.\n> \n> The build process now first creates the sphinx documentation and then\n> copies the doxygen documentation into the sphinx output directory.\n> \n> Signed-off-by: Stefan Klug \n> \n> ---\n> \n> ToDo:\n> - The meson custom targets still need some love. We need to decide what\n> gets installed and in what structure.\n> ---\n> Documentation/conf.py.in | 4 ++--\n> Documentation/index.rst | 31 +++++++++++++++++++------------\n> Documentation/introduction.rst | 6 ------\n> Documentation/meson.build | 21 +++++++++++++++++----\n> 4 files changed, 38 insertions(+), 24 deletions(-)\n> \n> diff --git a/Documentation/conf.py.in b/Documentation/conf.py.in\n> index 44e9aaf133ef..c772f643fb7c 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> \n> diff --git a/Documentation/index.rst b/Documentation/index.rst\n> index 251112fbdf5f..f6b9994c58c4 100644\n> --- a/Documentation/index.rst\n> +++ b/Documentation/index.rst\n> @@ -4,28 +4,35 @@\n> \n> .. toctree::\n> :maxdepth: 1\n> - :caption: Contents:\n> + :caption: For Users\n> +\n> + Introduction \n> + Feature Requirements \n> + Application Writer's Guide \n> + Python Bindings \n> + Environment variables \n> + Public-API \n\ns/Public-API/Public API/\n\nor maybe \"Pulic API Reference\" as written today on the website.\n\n> +\n> +.. toctree::\n> + :maxdepth: 1\n> + :caption: For Developers\n\nI expect the \"users\" in the above category to also be developers. I'm\nnot sure how to best name those two categories though. This can be\nimproved later.\n\n> \n> - Home \n> Contribute \n> Getting Started \n> -\n> - Application Writer's Guide \n> Camera Sensor Model \n> - Environment variables \n> - Feature Requirements \n> IPA Writer's guide \n> - Lens driver requirements \n> libcamera Architecture \n> Pipeline Handler Writer's Guide \n> - Python Bindings \n> - Sensor driver requirements \n> SoftwareISP Benchmarking \n> Tracing guide \n> -\n> Design document: AE \n> + Internal-API \n\ns/Internal-API/Internal API/\n\n> \n> .. toctree::\n> - :hidden:\n> + :maxdepth: 1\n> + :caption: For System Integrators\n> +\n> + Lens driver requirements \n> + Sensor driver requirements \n> +\n> \n> - introduction\n> diff --git a/Documentation/introduction.rst b/Documentation/introduction.rst\n> index 82aa11a30f33..d76cebd05ee1 100644\n> --- a/Documentation/introduction.rst\n> +++ b/Documentation/introduction.rst\n> @@ -6,12 +6,6 @@\n> Introduction\n> ************\n> \n> -.. toctree::\n> - :hidden:\n> -\n> - API \n> - Internal API \n> -\n> What is libcamera?\n> ==================\n> \n> diff --git a/Documentation/meson.build b/Documentation/meson.build\n> index f73407432fff..f9d17935749f 100644\n> --- a/Documentation/meson.build\n> +++ b/Documentation/meson.build\n> @@ -13,6 +13,7 @@ if doxygen.found() and dot.found()\n> cdata = configuration_data()\n> cdata.set('VERSION', 'v@0@'.format(libcamera_git_version))\n> cdata.set('TOP_SRCDIR', meson.project_source_root())\n> + cdata.set('CURRENT_SRCDIR', meson.current_source_dir())\n\nThis belongs to patch 2/6.\n\n> cdata.set('TOP_BUILDDIR', meson.project_build_root())\n> cdata.set('OUTPUT_DIR', meson.current_build_dir())\n> cdata.set('WARN_AS_ERROR', get_option('doc_werror') ? 'YES' : 'NO')\n> @@ -150,6 +151,7 @@ if sphinx.found()\n> sphinx_conf_dir = fs.parent(sphinx_conf)\n> \n> docs_sources = [\n> + 'api-html/index.rst',\n> 'camera-sensor-model.rst',\n> 'code-of-conduct.rst',\n> 'coding-style.rst',\n> @@ -164,6 +166,7 @@ if sphinx.found()\n> 'guides/pipeline-handler.rst',\n> 'guides/tracing.rst',\n> 'index.rst',\n> + 'internal-api-html/index.rst',\n> 'introduction.rst',\n> 'lens_driver_requirements.rst',\n> 'libcamera_architecture.rst',\n> @@ -176,17 +179,27 @@ if sphinx.found()\n> \n> release = 'release=v' + libcamera_git_version\n> \n> - custom_target('documentation',\n> +\n> +\n\nA single blank line should be enough.\n\n> + documentation_sphinx = custom_target('documentation-sphinx',\n> command : [sphinx, '-D', release, '-q', '-W', '-b', 'html',\n> '-c', sphinx_conf_dir,\n> - meson.current_source_dir(), '@OUTPUT@'],\n> + meson.current_source_dir(), '@OUTDIR@/html'],\n> input : docs_sources,\n> - output : 'html',\n> + output: 'sphinx-build',\n> build_by_default : true,\n> depends : [\n> doxygen_public,\n> doxygen_internal,\n> - ],\n> + ])\n\nWhy is this not installed anymore ?\n\n> +\n> + custom_target('documentation',\n> + command : ['cp', '-r', '@OUTDIR@/api-html', '@OUTDIR@/internal-api-html', '@OUTDIR@/html'],\n\nThat's not very nice :-/ Could we avoid the copy ? It's not clear from\nthe commit message why you need to do so.\n\n> + output : 'html',\n> + depends: [documentation_sphinx],\n> + build_by_default : true,\n> + build_always_stale : true,\n> + output: 'html',\n> install : true,\n> install_dir : doc_install_dir,\n> install_tag : 'doc')","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 D54FFBDB13\n\tfor ;\n\tWed, 10 Sep 2025 17:26:48 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 1796B69357;\n\tWed, 10 Sep 2025 19:26:47 +0200 (CEST)","from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[213.167.242.64])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id E51F269357\n\tfor ;\n\tWed, 10 Sep 2025 19:26:44 +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 A49F68BF;\n\tWed, 10 Sep 2025 19:25:30 +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=\"rjY/vhR6\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1757525130;\n\tbh=fsoRN42z/VGnibkfMPfEN8aiPFouBPa1KPOyfj91fXg=;\n\th=Date:From:To:Cc:Subject:References:In-Reply-To:From;\n\tb=rjY/vhR61YMnMjW3oRo1h6yB1s0pW1gbnSVhriy70sBVHH4D/hm8Hp+buLURJOAgs\n\tyIJs1JWsCktKQcwffjpPPs/emkusafGGJ2XlHO8KPmzFgJlayuUsB4AwEqGuTWTISq\n\tNuNT4MPQ6KhsaXQT5Rd+iCwT2qGGwMXrm1AA9Hy4=","Date":"Wed, 10 Sep 2025 20:26:21 +0300","From":"Laurent Pinchart ","To":"Stefan Klug ","Cc":"libcamera-devel@lists.libcamera.org","Subject":"Re: [PATCH 4/6] documentation: Include API docs in the sphinx\n\tdocumentation","Message-ID":"<20250910172621.GH20904@pendragon.ideasonboard.com>","References":"<20250908140803.123272-1-stefan.klug@ideasonboard.com>\n\t<20250908140803.123272-5-stefan.klug@ideasonboard.com>","MIME-Version":"1.0","Content-Type":"text/plain; charset=utf-8","Content-Disposition":"inline","In-Reply-To":"<20250908140803.123272-5-stefan.klug@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\" "}},{"id":35772,"web_url":"https://patchwork.libcamera.org/comment/35772/","msgid":"<20250910174155.GA32336@pendragon.ideasonboard.com>","date":"2025-09-10T17:41:55","subject":"Re: [PATCH 4/6] documentation: Include API docs in the sphinx\n\tdocumentation","submitter":{"id":2,"url":"https://patchwork.libcamera.org/api/people/2/","name":"Laurent Pinchart","email":"laurent.pinchart@ideasonboard.com"},"content":"On Mon, Sep 08, 2025 at 04:07:47PM +0200, Stefan Klug wrote:\n> This commit prepares the move of all the libcamera documetation to a\n> place separate from the website. This makes it easier to handle website\n> and docs separately.\n> \n> The index is updated to mimic the structure currently available on the\n> website.\n> \n> The build process now first creates the sphinx documentation and then\n> copies the doxygen documentation into the sphinx output directory.\n> \n> Signed-off-by: Stefan Klug \n> \n> ---\n> \n> ToDo:\n> - The meson custom targets still need some love. We need to decide what\n> gets installed and in what structure.\n> ---\n> Documentation/conf.py.in | 4 ++--\n> Documentation/index.rst | 31 +++++++++++++++++++------------\n> Documentation/introduction.rst | 6 ------\n> Documentation/meson.build | 21 +++++++++++++++++----\n> 4 files changed, 38 insertions(+), 24 deletions(-)\n> \n> diff --git a/Documentation/conf.py.in b/Documentation/conf.py.in\n> index 44e9aaf133ef..c772f643fb7c 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> \n> diff --git a/Documentation/index.rst b/Documentation/index.rst\n> index 251112fbdf5f..f6b9994c58c4 100644\n> --- a/Documentation/index.rst\n> +++ b/Documentation/index.rst\n> @@ -4,28 +4,35 @@\n> \n> .. toctree::\n> :maxdepth: 1\n> - :caption: Contents:\n> + :caption: For Users\n> +\n> + Introduction \n> + Feature Requirements \n> + Application Writer's Guide \n> + Python Bindings \n> + Environment variables \n> + Public-API \n> +\n> +.. toctree::\n> + :maxdepth: 1\n> + :caption: For Developers\n> \n> - Home \n> Contribute \n> Getting Started \n> -\n> - Application Writer's Guide \n> Camera Sensor Model \n> - Environment variables \n> - Feature Requirements \n> IPA Writer's guide \n> - Lens driver requirements \n> libcamera Architecture \n> Pipeline Handler Writer's Guide \n> - Python Bindings \n> - Sensor driver requirements \n> SoftwareISP Benchmarking \n> Tracing guide \n> -\n> Design document: AE \n> + Internal-API \n> \n> .. toctree::\n> - :hidden:\n> + :maxdepth: 1\n> + :caption: For System Integrators\n> +\n> + Lens driver requirements \n> + Sensor driver requirements \n> +\n> \n> - introduction\n> diff --git a/Documentation/introduction.rst b/Documentation/introduction.rst\n> index 82aa11a30f33..d76cebd05ee1 100644\n> --- a/Documentation/introduction.rst\n> +++ b/Documentation/introduction.rst\n> @@ -6,12 +6,6 @@\n> Introduction\n> ************\n> \n> -.. toctree::\n> - :hidden:\n> -\n> - API \n> - Internal API \n> -\n> What is libcamera?\n> ==================\n> \n> diff --git a/Documentation/meson.build b/Documentation/meson.build\n> index f73407432fff..f9d17935749f 100644\n> --- a/Documentation/meson.build\n> +++ b/Documentation/meson.build\n> @@ -13,6 +13,7 @@ if doxygen.found() and dot.found()\n> cdata = configuration_data()\n> cdata.set('VERSION', 'v@0@'.format(libcamera_git_version))\n> cdata.set('TOP_SRCDIR', meson.project_source_root())\n> + cdata.set('CURRENT_SRCDIR', meson.current_source_dir())\n> cdata.set('TOP_BUILDDIR', meson.project_build_root())\n> cdata.set('OUTPUT_DIR', meson.current_build_dir())\n> cdata.set('WARN_AS_ERROR', get_option('doc_werror') ? 'YES' : 'NO')\n> @@ -150,6 +151,7 @@ if sphinx.found()\n> sphinx_conf_dir = fs.parent(sphinx_conf)\n> \n> docs_sources = [\n> + 'api-html/index.rst',\n> 'camera-sensor-model.rst',\n> 'code-of-conduct.rst',\n> 'coding-style.rst',\n> @@ -164,6 +166,7 @@ if sphinx.found()\n> 'guides/pipeline-handler.rst',\n> 'guides/tracing.rst',\n> 'index.rst',\n> + 'internal-api-html/index.rst',\n> 'introduction.rst',\n> 'lens_driver_requirements.rst',\n> 'libcamera_architecture.rst',\n> @@ -176,17 +179,27 @@ if sphinx.found()\n> \n> release = 'release=v' + libcamera_git_version\n> \n> - custom_target('documentation',\n> +\n> +\n> + documentation_sphinx = custom_target('documentation-sphinx',\n> command : [sphinx, '-D', release, '-q', '-W', '-b', 'html',\n> '-c', sphinx_conf_dir,\n> - meson.current_source_dir(), '@OUTPUT@'],\n> + meson.current_source_dir(), '@OUTDIR@/html'],\n> input : docs_sources,\n> - output : 'html',\n> + output: 'sphinx-build',\n> build_by_default : true,\n> depends : [\n> doxygen_public,\n> doxygen_internal,\n> - ],\n> + ])\n> +\n> + custom_target('documentation',\n> + command : ['cp', '-r', '@OUTDIR@/api-html', '@OUTDIR@/internal-api-html', '@OUTDIR@/html'],\n> + output : 'html',\n> + depends: [documentation_sphinx],\n> + build_by_default : true,\n> + build_always_stale : true,\n> + output: 'html',\n\nThe 'output' argument is specified twice.\n\n> install : true,\n> install_dir : doc_install_dir,\n> install_tag : 'doc')","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 7407BBDB13\n\tfor ;\n\tWed, 10 Sep 2025 17:42:21 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 63F656936E;\n\tWed, 10 Sep 2025 19:42:20 +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 420A169357\n\tfor ;\n\tWed, 10 Sep 2025 19:42:19 +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 279EEE1F;\n\tWed, 10 Sep 2025 19:41: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=\"RjN/Rzl6\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1757526064;\n\tbh=KGlJ03LIcnmUyd6Wxfo08eqnmnfmTrr2hc4OAf1YNvs=;\n\th=Date:From:To:Cc:Subject:References:In-Reply-To:From;\n\tb=RjN/Rzl6jDHAVX/ov5TVsK6wka31n+Jh5lwmBlaF9slzhb3FXvd7a3bCknCBMl/my\n\tkcq8Nwvr5SQXyCZtkscnfwgH0rAJZkxErsLGECZ9V3Y7gHSAul+BmDLWg65zE9S+yY\n\tgm4QIkg7NjM8VbGsjfNIsr+M3Tn1D989qpE8B3Fc=","Date":"Wed, 10 Sep 2025 20:41:55 +0300","From":"Laurent Pinchart ","To":"Stefan Klug ","Cc":"libcamera-devel@lists.libcamera.org","Subject":"Re: [PATCH 4/6] documentation: Include API docs in the sphinx\n\tdocumentation","Message-ID":"<20250910174155.GA32336@pendragon.ideasonboard.com>","References":"<20250908140803.123272-1-stefan.klug@ideasonboard.com>\n\t<20250908140803.123272-5-stefan.klug@ideasonboard.com>","MIME-Version":"1.0","Content-Type":"text/plain; charset=utf-8","Content-Disposition":"inline","In-Reply-To":"<20250908140803.123272-5-stefan.klug@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\" "}}]