[v4,9/9] Documentation: Reformat documentation_contents.rst

20966 diff mbox series

Now that documentation_contents.rst serves as a navbar for the docs
pages on the website, reformat it to present the links in a more
logical order. The list is split into three sections for Users,
Developers and System Integrators, with a slight break between
each section and a header above the links.

Signed-off-by: Daniel Scally <dan.scally@ideasonboard.com>
---
Changes since v3:

	- New patch

 Documentation/documentation-contents.rst | 26 +++++++++++++++---------
 1 file changed, 16 insertions(+), 10 deletions(-)

Hi Dan,

Thank you for the patch.

On Tue, Aug 20, 2024 at 02:07:40PM +0100, Daniel Scally wrote:
> Now that documentation_contents.rst serves as a navbar for the docs
> pages on the website, reformat it to present the links in a more
> logical order. The list is split into three sections for Users,
> Developers and System Integrators, with a slight break between
> each section and a header above the links.
> 
> Signed-off-by: Daniel Scally <dan.scally@ideasonboard.com>
> ---
> Changes since v3:
> 
> 	- New patch
> 
>  Documentation/documentation-contents.rst | 26 +++++++++++++++---------
>  1 file changed, 16 insertions(+), 10 deletions(-)
> 
> diff --git a/Documentation/documentation-contents.rst b/Documentation/documentation-contents.rst
> index 912b13f3..4e7d1af9 100644
> --- a/Documentation/documentation-contents.rst
> +++ b/Documentation/documentation-contents.rst
> @@ -2,22 +2,28 @@
>  
>  .. container:: documentation-nav
>  
> -   * :doc:`/api-html/index`
> -   * :doc:`/internal-api-html/index`
> -   * :doc:`/camera-sensor-model`
> -   * :doc:`/code-of-conduct`
> -   * :doc:`/coding-style`
> -   * :doc:`/environment_variables`
> +   * **Documentation for Users**
> +   * :doc:`Introduction </introduction>`
>     * :doc:`/feature_requirements`
>     * :doc:`/guides/application-developer`
> -   * :doc:`/guides/ipa`
> +   * :doc:`/python-bindings`
> +   * :doc:`/environment_variables`
> +   * :doc:`API Reference </api-html/index>`
> +   * :doc:`/code-of-conduct`
> +   * |
> +   * **Documentation for Developers**

Instead of adding an empty entry and formatting the section headers with
**, I wonder if we could give them a class and handle the formatting in
CSS. This can be done on top, so

Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>

> +   * :doc:`/libcamera_architecture`
>     * :doc:`/guides/pipeline-handler`
> +   * :doc:`/guides/ipa`
> +   * :doc:`/camera-sensor-model`
>     * :doc:`/guides/tracing`
> +   * :doc:`/software-isp-benchmarking`
> +   * :doc:`/coding-style`
> +   * :doc:`Internal API Reference </internal-api-html/index>`
> +   * |
> +   * **Documentation for System Integrators**
>     * :doc:`/lens_driver_requirements`
> -   * :doc:`/libcamera_architecture`
> -   * :doc:`/python-bindings`
>     * :doc:`/sensor_driver_requirements`
> -   * :doc:`/software-isp-benchmarking`
>  
>  ..
>     The following directive adds the "documentation" class to all of the pages

Hi Laurent

On 20/08/2024 14:25, Laurent Pinchart wrote:
> Hi Dan,
>
> Thank you for the patch.
>
> On Tue, Aug 20, 2024 at 02:07:40PM +0100, Daniel Scally wrote:
>> Now that documentation_contents.rst serves as a navbar for the docs
>> pages on the website, reformat it to present the links in a more
>> logical order. The list is split into three sections for Users,
>> Developers and System Integrators, with a slight break between
>> each section and a header above the links.
>>
>> Signed-off-by: Daniel Scally <dan.scally@ideasonboard.com>
>> ---
>> Changes since v3:
>>
>> 	- New patch
>>
>>   Documentation/documentation-contents.rst | 26 +++++++++++++++---------
>>   1 file changed, 16 insertions(+), 10 deletions(-)
>>
>> diff --git a/Documentation/documentation-contents.rst b/Documentation/documentation-contents.rst
>> index 912b13f3..4e7d1af9 100644
>> --- a/Documentation/documentation-contents.rst
>> +++ b/Documentation/documentation-contents.rst
>> @@ -2,22 +2,28 @@
>>   
>>   .. container:: documentation-nav
>>   
>> -   * :doc:`/api-html/index`
>> -   * :doc:`/internal-api-html/index`
>> -   * :doc:`/camera-sensor-model`
>> -   * :doc:`/code-of-conduct`
>> -   * :doc:`/coding-style`
>> -   * :doc:`/environment_variables`
>> +   * **Documentation for Users**
>> +   * :doc:`Introduction </introduction>`
>>      * :doc:`/feature_requirements`
>>      * :doc:`/guides/application-developer`
>> -   * :doc:`/guides/ipa`
>> +   * :doc:`/python-bindings`
>> +   * :doc:`/environment_variables`
>> +   * :doc:`API Reference </api-html/index>`
>> +   * :doc:`/code-of-conduct`
>> +   * |
>> +   * **Documentation for Developers**
> Instead of adding an empty entry and formatting the section headers with
> **, I wonder if we could give them a class and handle the formatting in
> CSS.

With

.. role:: documentation-nav-header

    :class: documentation-nav-header


Followed by something like


* :documentation-nav-header:`Documentation for Users`


Which then wraps the header in a new span with that class. I did start down that route but it seemed 
much clunkier, but perhaps it can be made to work nicely with more effort

> This can be done on top, so
>
> Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>


Thanks

>> +   * :doc:`/libcamera_architecture`
>>      * :doc:`/guides/pipeline-handler`
>> +   * :doc:`/guides/ipa`
>> +   * :doc:`/camera-sensor-model`
>>      * :doc:`/guides/tracing`
>> +   * :doc:`/software-isp-benchmarking`
>> +   * :doc:`/coding-style`
>> +   * :doc:`Internal API Reference </internal-api-html/index>`
>> +   * |
>> +   * **Documentation for System Integrators**
>>      * :doc:`/lens_driver_requirements`
>> -   * :doc:`/libcamera_architecture`
>> -   * :doc:`/python-bindings`
>>      * :doc:`/sensor_driver_requirements`
>> -   * :doc:`/software-isp-benchmarking`
>>   
>>   ..
>>      The following directive adds the "documentation" class to all of the pages