[{"id":30824,"web_url":"https://patchwork.libcamera.org/comment/30824/","msgid":"<20240815002449.GI22567@pendragon.ideasonboard.com>","date":"2024-08-15T00:24:49","subject":"Re: [PATCH 7/7] Documentation: Rework index.rst","submitter":{"id":2,"url":"https://patchwork.libcamera.org/api/people/2/","name":"Laurent Pinchart","email":"laurent.pinchart@ideasonboard.com"},"content":"Hi Dan,\n\nThank you for the patch.\n\nOn Fri, Aug 09, 2024 at 03:53:04PM +0100, Daniel Scally wrote:\n> index.rst is the page that becomes index.html, but currently just has\n> some blurb. Although this page will only be seen if viewing the docs\n> as built from the libcamera tree it'd be better if it were more of an\n> introductory page. Include the content of docs.rst to improve it.\n> \n> With this change whether viewing the documentation as built in the\n> libcamera tree or on the Docs page of the website, the landing content\n> will be the same.\n> \n> The CSS for the documentation's theme is updated so that section ID\n> references still fix the right problem.\n\nSorry, what's the right problem ?\n\n> Signed-off-by: Daniel Scally <dan.scally@ideasonboard.com>\n> ---\n>  Documentation/index.rst                  | 10 ++++++----\n>  Documentation/theme/static/css/theme.css |  2 +-\n>  2 files changed, 7 insertions(+), 5 deletions(-)\n> \n> diff --git a/Documentation/index.rst b/Documentation/index.rst\n> index 6d7d2ca3..0fe10706 100644\n> --- a/Documentation/index.rst\n> +++ b/Documentation/index.rst\n> @@ -1,16 +1,13 @@\n>  .. SPDX-License-Identifier: CC-BY-SA-4.0\n>  \n>  .. Front page matter is defined in the project README file.\n\nThis comment seems outdated.\n\n> -.. include:: ../README.rst\n> -   :start-after: .. section-begin-libcamera\n> -   :end-before: .. section-end-libcamera\n\nI think this means you can drop the section-begin-libcamera and\nsection-end-libcamera labels from README.rst.\n\n> +.. include:: docs.rst\n>  \n>  .. toctree::\n>     :maxdepth: 1\n>     :caption: Contents:\n>  \n>     Home <self>\n> -   Docs <docs>\n\nIt makes sense to drop this, but the Docs section is included in the toc\ntree of every other page. Should it be dropped from there too (I assume\nso), and can it easily be done ?\n\n>     Contribute <contributing>\n>     Getting Started <getting-started>\n>  \n> @@ -26,3 +23,8 @@\n>     Sensor driver requirements <sensor_driver_requirements>\n>     SoftwareISP Benchmarking <software-isp-benchmarking>\n>     Tracing guide <guides/tracing>\n> +\n> +.. toctree::\n> +   :hidden:\n> +\n> +   docs\n> \\ No newline at end of file\n> diff --git a/Documentation/theme/static/css/theme.css b/Documentation/theme/static/css/theme.css\n> index 2b1ed095..a6d43195 100644\n> --- a/Documentation/theme/static/css/theme.css\n> +++ b/Documentation/theme/static/css/theme.css\n> @@ -283,7 +283,7 @@ div#signature {\n>  \tfont-size: 12px;\n>  }\n>  \n> -#libcamera div.toctree-wrapper {\n> +#licensing div.toctree-wrapper {\n>  \theight: 0px;\n>  \tmargin: 0px;\n>  \tpadding: 0px;","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 72DB9C323E\n\tfor <parsemail@patchwork.libcamera.org>;\n\tThu, 15 Aug 2024 00:25:19 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 83EF363394;\n\tThu, 15 Aug 2024 02:25:18 +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 E685363382\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tThu, 15 Aug 2024 02:25:15 +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 96DA3AD8;\n\tThu, 15 Aug 2024 02:24:17 +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=\"HHkuYf95\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1723681457;\n\tbh=Le5GmdxVjsou3B7YOvpZR5d/JjN+tRBTm+Acr3PMR5A=;\n\th=Date:From:To:Cc:Subject:References:In-Reply-To:From;\n\tb=HHkuYf95XvdeFc8Q7WOI6XnM8snDZtLUL4llHLfvJn63+RMEbohVAW8Cm0GRTtYJ2\n\tV12YTCtwkXLKxedKi+JF1lPCF2qpS9ggKSdwMY569ArtIGN95CdXPiWmmngSFr1X8+\n\trPXBtgPoMLzjWo0TuZh3ImQ29R7VE3ESV889+Lb8=","Date":"Thu, 15 Aug 2024 03:24:49 +0300","From":"Laurent Pinchart <laurent.pinchart@ideasonboard.com>","To":"Daniel Scally <dan.scally@ideasonboard.com>","Cc":"libcamera-devel@lists.libcamera.org","Subject":"Re: [PATCH 7/7] Documentation: Rework index.rst","Message-ID":"<20240815002449.GI22567@pendragon.ideasonboard.com>","References":"<20240809145304.537551-1-dan.scally@ideasonboard.com>\n\t<20240809145304.537551-8-dan.scally@ideasonboard.com>","MIME-Version":"1.0","Content-Type":"text/plain; charset=utf-8","Content-Disposition":"inline","In-Reply-To":"<20240809145304.537551-8-dan.scally@ideasonboard.com>","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>"}},{"id":30837,"web_url":"https://patchwork.libcamera.org/comment/30837/","msgid":"<d9616494-a244-45f4-bc3c-57cddc8ae7f6@ideasonboard.com>","date":"2024-08-15T07:23:22","subject":"Re: [PATCH 7/7] Documentation: Rework index.rst","submitter":{"id":156,"url":"https://patchwork.libcamera.org/api/people/156/","name":"Dan Scally","email":"dan.scally@ideasonboard.com"},"content":"Hi Laurent - thanks for the review\n\nOn 15/08/2024 01:24, Laurent Pinchart wrote:\n> Hi Dan,\n>\n> Thank you for the patch.\n>\n> On Fri, Aug 09, 2024 at 03:53:04PM +0100, Daniel Scally wrote:\n>> index.rst is the page that becomes index.html, but currently just has\n>> some blurb. Although this page will only be seen if viewing the docs\n>> as built from the libcamera tree it'd be better if it were more of an\n>> introductory page. Include the content of docs.rst to improve it.\n>>\n>> With this change whether viewing the documentation as built in the\n>> libcamera tree or on the Docs page of the website, the landing content\n>> will be the same.\n>>\n>> The CSS for the documentation's theme is updated so that section ID\n>> references still fix the right problem.\n> Sorry, what's the right problem ?\n\n\nAh; the current implementation hides the toctree in the generated body as it's already shown via the \ntheme's template file; this change upsets that and so the CSS needed to be corrected to account for \nit. I'll make that more clear.\n\n>\n>> Signed-off-by: Daniel Scally <dan.scally@ideasonboard.com>\n>> ---\n>>   Documentation/index.rst                  | 10 ++++++----\n>>   Documentation/theme/static/css/theme.css |  2 +-\n>>   2 files changed, 7 insertions(+), 5 deletions(-)\n>>\n>> diff --git a/Documentation/index.rst b/Documentation/index.rst\n>> index 6d7d2ca3..0fe10706 100644\n>> --- a/Documentation/index.rst\n>> +++ b/Documentation/index.rst\n>> @@ -1,16 +1,13 @@\n>>   .. SPDX-License-Identifier: CC-BY-SA-4.0\n>>   \n>>   .. Front page matter is defined in the project README file.\n> This comment seems outdated.\n>\n>> -.. include:: ../README.rst\n>> -   :start-after: .. section-begin-libcamera\n>> -   :end-before: .. section-end-libcamera\n> I think this means you can drop the section-begin-libcamera and\n> section-end-libcamera labels from README.rst.\n>\n>> +.. include:: docs.rst\n>>   \n>>   .. toctree::\n>>      :maxdepth: 1\n>>      :caption: Contents:\n>>   \n>>      Home <self>\n>> -   Docs <docs>\n> It makes sense to drop this, but the Docs section is included in the toc\n> tree of every other page. Should it be dropped from there too (I assume\n> so), and can it easily be done ?\n\n\nWhich other page sorry? I can't see it in a toctree elsewhere.\n\n>>      Contribute <contributing>\n>>      Getting Started <getting-started>\n>>   \n>> @@ -26,3 +23,8 @@\n>>      Sensor driver requirements <sensor_driver_requirements>\n>>      SoftwareISP Benchmarking <software-isp-benchmarking>\n>>      Tracing guide <guides/tracing>\n>> +\n>> +.. toctree::\n>> +   :hidden:\n>> +\n>> +   docs\n>> \\ No newline at end of file\n>> diff --git a/Documentation/theme/static/css/theme.css b/Documentation/theme/static/css/theme.css\n>> index 2b1ed095..a6d43195 100644\n>> --- a/Documentation/theme/static/css/theme.css\n>> +++ b/Documentation/theme/static/css/theme.css\n>> @@ -283,7 +283,7 @@ div#signature {\n>>   \tfont-size: 12px;\n>>   }\n>>   \n>> -#libcamera div.toctree-wrapper {\n>> +#licensing div.toctree-wrapper {\n>>   \theight: 0px;\n>>   \tmargin: 0px;\n>>   \tpadding: 0px;","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 E41F8BDB13\n\tfor <parsemail@patchwork.libcamera.org>;\n\tThu, 15 Aug 2024 07:23:28 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id CCED8633BD;\n\tThu, 15 Aug 2024 09:23:27 +0200 (CEST)","from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[213.167.242.64])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 7198163393\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tThu, 15 Aug 2024 09:23:25 +0200 (CEST)","from [192.168.0.43]\n\t(cpc141996-chfd3-2-0-cust928.12-3.cable.virginm.net [86.13.91.161])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id 1F008827;\n\tThu, 15 Aug 2024 09:22:27 +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=\"LPCD1y7z\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1723706547;\n\tbh=qylMUMBZVtyVkhzFmA9sMm3rogVBij6EiXz6G6GCE6A=;\n\th=Date:Subject:To:Cc:References:From:In-Reply-To:From;\n\tb=LPCD1y7zRj0U1KiDDE2aD/ZfqM001HCqblNGkbatQSW0hpiQ41a48CddAaK8a1VTe\n\tNwzHjdvaAUyiR0km4YGvgY2kgJURaiPmNZplNun6AGmSKv2K+DsZF8+SmMwa08xZWG\n\tYPskNRaoBSkjqKdFiYYV9qAlDADR/eUKtmkHMj9w=","Message-ID":"<d9616494-a244-45f4-bc3c-57cddc8ae7f6@ideasonboard.com>","Date":"Thu, 15 Aug 2024 08:23:22 +0100","MIME-Version":"1.0","User-Agent":"Mozilla Thunderbird","Subject":"Re: [PATCH 7/7] Documentation: Rework index.rst","To":"Laurent Pinchart <laurent.pinchart@ideasonboard.com>","Cc":"libcamera-devel@lists.libcamera.org","References":"<20240809145304.537551-1-dan.scally@ideasonboard.com>\n\t<20240809145304.537551-8-dan.scally@ideasonboard.com>\n\t<20240815002449.GI22567@pendragon.ideasonboard.com>","Content-Language":"en-US","From":"Dan Scally <dan.scally@ideasonboard.com>","Autocrypt":"addr=dan.scally@ideasonboard.com; keydata=\n\t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","In-Reply-To":"<20240815002449.GI22567@pendragon.ideasonboard.com>","Content-Type":"text/plain; charset=UTF-8; format=flowed","Content-Transfer-Encoding":"7bit","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>"}}]