[PATCH 1/7] Documentation: Add documentation-contents.rst
Dan Scally
dan.scally at ideasonboard.com
Thu Aug 15 00:22:53 CEST 2024
Hi Laurent
On 14/08/2024 23:18, Laurent Pinchart wrote:
> Hi Dan,
>
> Thank you for the patch.
>
> On Fri, Aug 09, 2024 at 03:52:58PM +0100, Daniel Scally wrote:
>> Add a new .rst file referencing the documentation contents. This file
>> is then included in each documentation page so that we can enhance
>> the Documentation pages on the libcamera website using it. As we do
>> not want the appearance of the libcamera in-tree Documentation to
>> change just yet, disable the new class using the sphinx theme's CSS.
>>
>> Signed-off-by: Daniel Scally <dan.scally at ideasonboard.com>
>> ---
>> Documentation/camera-sensor-model.rst | 2 ++
>> Documentation/code-of-conduct.rst | 2 ++
>> Documentation/coding-style.rst | 2 ++
>> Documentation/conf.py | 7 ++++++-
>> Documentation/docs.rst | 2 ++
>> Documentation/documentation-contents.rst | 20 +++++++++++++++++++
>> Documentation/environment_variables.rst | 2 ++
>> Documentation/getting-started.rst | 1 +
>> .../guides/application-developer.rst | 2 ++
>> Documentation/guides/introduction.rst | 2 ++
>> Documentation/guides/ipa.rst | 2 ++
>> Documentation/guides/pipeline-handler.rst | 2 ++
>> Documentation/guides/tracing.rst | 2 ++
>> Documentation/lens_driver_requirements.rst | 2 ++
>> Documentation/python-bindings.rst | 2 ++
>> Documentation/sensor_driver_requirements.rst | 2 ++
>> Documentation/software-isp-benchmarking.rst | 2 ++
>> Documentation/theme/static/css/theme.css | 4 ++++
>> 18 files changed, 59 insertions(+), 1 deletion(-)
>> create mode 100644 Documentation/documentation-contents.rst
>>
>> diff --git a/Documentation/camera-sensor-model.rst b/Documentation/camera-sensor-model.rst
>> index b66c880a..87a25bf4 100644
>> --- a/Documentation/camera-sensor-model.rst
>> +++ b/Documentation/camera-sensor-model.rst
>> @@ -1,5 +1,7 @@
>> .. SPDX-License-Identifier: CC-BY-SA-4.0
>>
>> +.. include:: documentation-contents.rst
>> +
>> .. _camera-sensor-model:
>>
>> .. todo: Move to Doxygen-generated documentation
>> diff --git a/Documentation/code-of-conduct.rst b/Documentation/code-of-conduct.rst
>> index 38b7d7ad..0edd1e99 100644
>> --- a/Documentation/code-of-conduct.rst
>> +++ b/Documentation/code-of-conduct.rst
>> @@ -1,5 +1,7 @@
>> .. SPDX-License-Identifier: CC-BY-4.0
>>
>> +.. include:: documentation-contents.rst
>> +
>> .. _code-of-conduct:
>>
>> Contributor Covenant Code of Conduct
> I'm not sure this should be included in the technical documentation as
> such, but we can fine-tune what goes where later.
>
>> diff --git a/Documentation/coding-style.rst b/Documentation/coding-style.rst
>> index 72cb28d2..ae8446bd 100644
>> --- a/Documentation/coding-style.rst
>> +++ b/Documentation/coding-style.rst
>> @@ -1,5 +1,7 @@
>> .. SPDX-License-Identifier: CC-BY-SA-4.0
>>
>> +.. include:: documentation-contents.rst
>> +
>> .. _coding-style-guidelines:
>>
>> Coding Style Guidelines
>> diff --git a/Documentation/conf.py b/Documentation/conf.py
>> index 7eeea7f3..ca817aab 100644
>> --- a/Documentation/conf.py
>> +++ b/Documentation/conf.py
>> @@ -61,7 +61,12 @@ language = 'en'
>> # List of patterns, relative to source directory, that match files and
>> # directories to ignore when looking for source files.
>> # This pattern also affects html_static_path and html_extra_path.
>> -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
>> +exclude_patterns = [
>> + '_build',
>> + 'Thumbs.db',
>> + '.DS_Store',
>> + 'documentation-contents.rst',
>> + ]
> The closing bracket should be on the first column.
>
>>
>> # The name of the Pygments (syntax highlighting) style to use.
>> pygments_style = None
>> diff --git a/Documentation/docs.rst b/Documentation/docs.rst
>> index a6e8a59a..5871961c 100644
>> --- a/Documentation/docs.rst
>> +++ b/Documentation/docs.rst
>> @@ -3,6 +3,8 @@
>> .. contents::
>> :local:
>>
>> +.. include:: documentation-contents.rst
>> +
>> *************
>> Documentation
>> *************
>> diff --git a/Documentation/documentation-contents.rst b/Documentation/documentation-contents.rst
>> new file mode 100644
>> index 00000000..e9a3846b
>> --- /dev/null
>> +++ b/Documentation/documentation-contents.rst
>> @@ -0,0 +1,20 @@
>> +.. SPDX-License-Identifier: CC-BY-SA-4.0
>> +
>> +.. container:: documentation-nav
>> +
>> + * :doc:`/api-html/index`
>> + * :doc:`/camera-sensor-model`
>> + * :doc:`/code-of-conduct`
>> + * :doc:`/coding-style`
>> + * :doc:`/environment_variables`
>> + * :doc:`/guides/application-developer`
>> + * :doc:`/guides/introduction`
>> + * :doc:`/guides/ipa`
>> + * :doc:`/guides/pipeline-handler`
>> + * :doc:`/guides/tracing`
>> + * :doc:`/lens_driver_requirements`
>> + * :doc:`/python-bindings`
>> + * :doc:`/sensor_driver_requirements`
>> + * :doc:`/software-isp-benchmarking`
>> +
>> +.. rst-class:: documentation
> What is this class for ? It doesn't seem to be defined yet, does it
> belong to a different patch in the series ?
Possibly this could have been explained better; adding the "documentation" class to the body of the
documentation pages lets us control them as one through the CSS. Having this setting as the last
line of this file and then including this file in each documentation file was the simplest way to
add it to all of them.
>
> Reviewed-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
>
>> diff --git a/Documentation/environment_variables.rst b/Documentation/environment_variables.rst
>> index 4e9fbb27..1478275b 100644
>> --- a/Documentation/environment_variables.rst
>> +++ b/Documentation/environment_variables.rst
>> @@ -1,5 +1,7 @@
>> .. SPDX-License-Identifier: CC-BY-SA-4.0
>>
>> +.. include:: documentation-contents.rst
>> +
>> Environment variables
>> =====================
>>
>> diff --git a/Documentation/getting-started.rst b/Documentation/getting-started.rst
>> index 987f43f7..63b050eb 100644
>> --- a/Documentation/getting-started.rst
>> +++ b/Documentation/getting-started.rst
>> @@ -1,4 +1,5 @@
>> .. SPDX-License-Identifier: CC-BY-SA-4.0
>> +
>> .. Getting started information is defined in the project README file.
>> .. include:: ../README.rst
>> :start-after: .. section-begin-getting-started
>> diff --git a/Documentation/guides/application-developer.rst b/Documentation/guides/application-developer.rst
>> index 92e2a373..1ea8c40f 100644
>> --- a/Documentation/guides/application-developer.rst
>> +++ b/Documentation/guides/application-developer.rst
>> @@ -1,5 +1,7 @@
>> .. SPDX-License-Identifier: CC-BY-SA-4.0
>>
>> +.. include:: ../documentation-contents.rst
>> +
>> Using libcamera in a C++ application
>> ====================================
>>
>> diff --git a/Documentation/guides/introduction.rst b/Documentation/guides/introduction.rst
>> index 700ec2d3..8368bd4a 100644
>> --- a/Documentation/guides/introduction.rst
>> +++ b/Documentation/guides/introduction.rst
>> @@ -1,5 +1,7 @@
>> .. SPDX-License-Identifier: CC-BY-SA-4.0
>>
>> +.. include:: ../documentation-contents.rst
>> +
>> Developers guide to libcamera
>> =============================
>>
>> diff --git a/Documentation/guides/ipa.rst b/Documentation/guides/ipa.rst
>> index 25deadef..cd640563 100644
>> --- a/Documentation/guides/ipa.rst
>> +++ b/Documentation/guides/ipa.rst
>> @@ -1,5 +1,7 @@
>> .. SPDX-License-Identifier: CC-BY-SA-4.0
>>
>> +.. include:: ../documentation-contents.rst
>> +
>> IPA Writer's Guide
>> ==================
>>
>> diff --git a/Documentation/guides/pipeline-handler.rst b/Documentation/guides/pipeline-handler.rst
>> index 7e45cdb8..efa89342 100644
>> --- a/Documentation/guides/pipeline-handler.rst
>> +++ b/Documentation/guides/pipeline-handler.rst
>> @@ -1,5 +1,7 @@
>> .. SPDX-License-Identifier: CC-BY-SA-4.0
>>
>> +.. include:: ../documentation-contents.rst
>> +
>> Pipeline Handler Writers Guide
>> ==============================
>>
>> diff --git a/Documentation/guides/tracing.rst b/Documentation/guides/tracing.rst
>> index ae960d85..537dce50 100644
>> --- a/Documentation/guides/tracing.rst
>> +++ b/Documentation/guides/tracing.rst
>> @@ -1,5 +1,7 @@
>> .. SPDX-License-Identifier: CC-BY-SA-4.0
>>
>> +.. include:: ../documentation-contents.rst
>> +
>> Tracing Guide
>> =============
>>
>> diff --git a/Documentation/lens_driver_requirements.rst b/Documentation/lens_driver_requirements.rst
>> index b96e502d..85fef76f 100644
>> --- a/Documentation/lens_driver_requirements.rst
>> +++ b/Documentation/lens_driver_requirements.rst
>> @@ -1,5 +1,7 @@
>> .. SPDX-License-Identifier: CC-BY-SA-4.0
>>
>> +.. include:: documentation-contents.rst
>> +
>> .. _lens-driver-requirements:
>>
>> Lens Driver Requirements
>> diff --git a/Documentation/python-bindings.rst b/Documentation/python-bindings.rst
>> index ed9f686b..94712238 100644
>> --- a/Documentation/python-bindings.rst
>> +++ b/Documentation/python-bindings.rst
>> @@ -1,5 +1,7 @@
>> .. SPDX-License-Identifier: CC-BY-SA-4.0
>>
>> +.. include:: documentation-contents.rst
>> +
>> .. _python-bindings:
>>
>> Python Bindings for libcamera
>> diff --git a/Documentation/sensor_driver_requirements.rst b/Documentation/sensor_driver_requirements.rst
>> index 0e516b34..fb4269d0 100644
>> --- a/Documentation/sensor_driver_requirements.rst
>> +++ b/Documentation/sensor_driver_requirements.rst
>> @@ -1,5 +1,7 @@
>> .. SPDX-License-Identifier: CC-BY-SA-4.0
>>
>> +.. include:: documentation-contents.rst
>> +
>> .. _sensor-driver-requirements:
>>
>> Sensor Driver Requirements
>> diff --git a/Documentation/software-isp-benchmarking.rst b/Documentation/software-isp-benchmarking.rst
>> index b3033132..9c2a409b 100644
>> --- a/Documentation/software-isp-benchmarking.rst
>> +++ b/Documentation/software-isp-benchmarking.rst
>> @@ -1,5 +1,7 @@
>> .. SPDX-License-Identifier: CC-BY-SA-4.0
>>
>> +.. include:: documentation-contents.rst
>> +
>> .. _software-isp-benchmarking:
>>
>> Software ISP benchmarking
>> diff --git a/Documentation/theme/static/css/theme.css b/Documentation/theme/static/css/theme.css
>> index d4274ea6..2b1ed095 100644
>> --- a/Documentation/theme/static/css/theme.css
>> +++ b/Documentation/theme/static/css/theme.css
>> @@ -289,3 +289,7 @@ div#signature {
>> padding: 0px;
>> visibility: hidden;
>> }
>> +
>> +.documentation-nav {
>> + display: none;
>> +}
More information about the libcamera-devel
mailing list