[PATCH 7/7] Documentation: Rework index.rst

[Dan Scally]

Hi Laurent - thanks for the review

On 15/08/2024 01:24, Laurent Pinchart wrote:
> Hi Dan,
>
> Thank you for the patch.
>
> On Fri, Aug 09, 2024 at 03:53:04PM +0100, Daniel Scally wrote:
>> index.rst is the page that becomes index.html, but currently just has
>> some blurb. Although this page will only be seen if viewing the docs
>> as built from the libcamera tree it'd be better if it were more of an
>> introductory page. Include the content of docs.rst to improve it.
>>
>> With this change whether viewing the documentation as built in the
>> libcamera tree or on the Docs page of the website, the landing content
>> will be the same.
>>
>> The CSS for the documentation's theme is updated so that section ID
>> references still fix the right problem.
> Sorry, what's the right problem ?


Ah; the current implementation hides the toctree in the generated body as it's already shown via the 
theme's template file; this change upsets that and so the CSS needed to be corrected to account for 
it. I'll make that more clear.

>
>> Signed-off-by: Daniel Scally <dan.scally at ideasonboard.com>
>> ---
>>   Documentation/index.rst                  | 10 ++++++----
>>   Documentation/theme/static/css/theme.css |  2 +-
>>   2 files changed, 7 insertions(+), 5 deletions(-)
>>
>> diff --git a/Documentation/index.rst b/Documentation/index.rst
>> index 6d7d2ca3..0fe10706 100644
>> --- a/Documentation/index.rst
>> +++ b/Documentation/index.rst
>> @@ -1,16 +1,13 @@
>>   .. SPDX-License-Identifier: CC-BY-SA-4.0
>>   
>>   .. Front page matter is defined in the project README file.
> This comment seems outdated.
>
>> -.. include:: ../README.rst
>> -   :start-after: .. section-begin-libcamera
>> -   :end-before: .. section-end-libcamera
> I think this means you can drop the section-begin-libcamera and
> section-end-libcamera labels from README.rst.
>
>> +.. include:: docs.rst
>>   
>>   .. toctree::
>>      :maxdepth: 1
>>      :caption: Contents:
>>   
>>      Home <self>
>> -   Docs <docs>
> It makes sense to drop this, but the Docs section is included in the toc
> tree of every other page. Should it be dropped from there too (I assume
> so), and can it easily be done ?


Which other page sorry? I can't see it in a toctree elsewhere.

>>      Contribute <contributing>
>>      Getting Started <getting-started>
>>   
>> @@ -26,3 +23,8 @@
>>      Sensor driver requirements <sensor_driver_requirements>
>>      SoftwareISP Benchmarking <software-isp-benchmarking>
>>      Tracing guide <guides/tracing>
>> +
>> +.. toctree::
>> +   :hidden:
>> +
>> +   docs
>> \ No newline at end of file
>> diff --git a/Documentation/theme/static/css/theme.css b/Documentation/theme/static/css/theme.css
>> index 2b1ed095..a6d43195 100644
>> --- a/Documentation/theme/static/css/theme.css
>> +++ b/Documentation/theme/static/css/theme.css
>> @@ -283,7 +283,7 @@ div#signature {
>>   	font-size: 12px;
>>   }
>>   
>> -#libcamera div.toctree-wrapper {
>> +#licensing div.toctree-wrapper {
>>   	height: 0px;
>>   	margin: 0px;
>>   	padding: 0px;