[{"id":35889,"web_url":"https://patchwork.libcamera.org/comment/35889/","msgid":"<11d25810-d21d-4ba6-9cc0-ae18a6562739@ideasonboard.com>","date":"2025-09-18T11:54:50","subject":"Re: [PATCH v3 06/10] Documentation: Reorganize toctree","submitter":{"id":216,"url":"https://patchwork.libcamera.org/api/people/216/","name":"Barnabás Pőcze","email":"barnabas.pocze@ideasonboard.com"},"content":"2025. 09. 17. 22:17 keltezéssel, Laurent Pinchart írta:\n> From: Stefan Klug \n> \n> The libcamera Sphinx documentation contains three toctrees: a main\n> toctree that contains all documentation pages in a flat hierarchy, and\n> two hidden toctrees that point to the introduction and API pages. This\n> architecture is mostly meant to support publishing the documentation on\n> the libcamera.org website. The process recreates a hybrid documentation\n> tree mixing content specific to the website and content extracted from\n> libcamera. The hidden toctrees are used to prevent Sphinx from warning\n> about unreferenced pages when the documentation is built as part of\n> libcamera.\n> \n> This set of hacks work, but produce unorganized documentation in the\n> build directory, as well as when installed to the system. Furthermore,\n> they make it difficult to host multiple versions of the libcamera\n> documentation on the website, which we will eventually want to do as the\n> API stabilizes. It would be generally better to host on libcamera.org\n> the documentation built as part of libcamera with the same structure of\n> documents.\n> \n> To prepare for that change, reorganize the toctrees in libcamera with\n> three visible trees: a toctree for users, a toctree for developers, and\n> a toctree for integrators. Include the public and internal API pages\n> in the first two trees respectively. This mimics the structure of the\n> documentation as currently organized on the website. The resulting\n> documentation becomes easier to navigate in the build and installation\n> directories.\n> \n> Signed-off-by: Stefan Klug \n> Signed-off-by: Laurent Pinchart \n> ---\n> Changes since v2:\n> \n> - Update commit message\n> \n> Changes since v1:\n> \n> - Split the build changes to a separate patch\n> ---\n\nReviewed-by: Barnabás Pőcze \n\n\n> Documentation/index.rst | 45 ++++++++++++++++++++--------------\n> Documentation/introduction.rst | 6 -----\n> 2 files changed, 26 insertions(+), 25 deletions(-)\n> \n> diff --git a/Documentation/index.rst b/Documentation/index.rst\n> index 251112fbdf5f..d55b5ff21464 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> - Home \n> - Contribute \n> - Getting Started \n> -\n> - Application Writer's Guide \n> - Camera Sensor Model \n> - Environment variables \n> + Introduction \n> Feature Requirements \n> - IPA Writer's guide \n> - Lens driver requirements \n> - libcamera Architecture \n> - Pipeline Handler Writer's Guide \n> + Application Writer's Guide \n> Python Bindings \n> - Sensor driver requirements \n> - SoftwareISP Benchmarking \n> - Tracing guide \n> -\n> - Design document: AE \n> + Environment variables \n> + Public API \n> \n> .. toctree::\n> - :hidden:\n> + :maxdepth: 1\n> + :caption: For Developers\n> +\n> + Contribute \n> + Getting Started \n> + Camera Sensor Model \n> + IPA Writer's guide \n> + libcamera Architecture \n> + Pipeline Handler Writer's Guide \n> + SoftwareISP Benchmarking \n> + Tracing guide \n> + Design document: AE \n> + Internal API \n> +\n> +.. toctree::\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>","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 4E37DBE173\n\tfor ;\n\tThu, 18 Sep 2025 11:54:58 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 021136936F;\n\tThu, 18 Sep 2025 13:54:56 +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 B2ED662C3B\n\tfor ;\n\tThu, 18 Sep 2025 13:54:54 +0200 (CEST)","from [192.168.33.22] (185.221.142.115.nat.pool.zt.hu\n\t[185.221.142.115])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id D16BF520;\n\tThu, 18 Sep 2025 13:53:34 +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=\"SW18m9TF\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1758196415;\n\tbh=msUzOC90U25ojIo4QbbrGwiCxtJqgcKXn2lIhHmrY9w=;\n\th=Date:Subject:To:Cc:References:From:In-Reply-To:From;\n\tb=SW18m9TFdd8TbfZ9OxHv/PGNEm7xPkWx3Pflx29w6cPRbNs73CkWGvTONq1gl7Od4\n\tgT0+Epv6+JKPMWKfIwIUnOl+zQnd9j+2415O+fJ7U+XdzkEuz2aomtdxrC+FJeWCmZ\n\tNjPH1H06vUSQ9V1Z9FQI8Mpul7EI+eCdw6iUELQk=","Message-ID":"<11d25810-d21d-4ba6-9cc0-ae18a6562739@ideasonboard.com>","Date":"Thu, 18 Sep 2025 13:54:50 +0200","MIME-Version":"1.0","User-Agent":"Mozilla Thunderbird","Subject":"Re: [PATCH v3 06/10] Documentation: Reorganize toctree","To":"Laurent Pinchart ,\n\tlibcamera-devel@lists.libcamera.org","Cc":"Stefan Klug ","References":"<20250917201742.16406-1-laurent.pinchart@ideasonboard.com>\n\t<20250917201742.16406-7-laurent.pinchart@ideasonboard.com>","From":"=?utf-8?q?Barnab=C3=A1s_P=C5=91cze?= ","Content-Language":"en-US, hu-HU","In-Reply-To":"<20250917201742.16406-7-laurent.pinchart@ideasonboard.com>","Content-Type":"text/plain; charset=UTF-8; format=flowed","Content-Transfer-Encoding":"8bit","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\" "}}]