From 182bdadd0f09791c94372a34c3e73564b335ada4 Mon Sep 17 00:00:00 2001 From: Daniel Scally Date: Tue, 20 Aug 2024 14:07:32 +0100 Subject: [PATCH] Documentation: Add documentation-contents.rst 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. To facilitate easier distinguishing between "normal" and documentation pages on the website we want to add a "documentation" class to the content of all such pages. Since this new file will be included on each documentation page it is convenient to add the new directive here - do so. As the website uses different CSS to libcamera, move the contents on docs.rst a little so that the directive at the end of the contents block applies correctly. Reviewed-by: Laurent Pinchart Signed-off-by: Daniel Scally Signed-off-by: Laurent Pinchart --- 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 | 27 +++++++++++++++++++ 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/meson.build | 1 + Documentation/python-bindings.rst | 2 ++ Documentation/sensor_driver_requirements.rst | 2 ++ Documentation/software-isp-benchmarking.rst | 2 ++ Documentation/theme/static/css/theme.css | 4 +++ 19 files changed, 67 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 b66c880a5..87a25bf4a 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 38b7d7ad6..0edd1e995 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 diff --git a/Documentation/coding-style.rst b/Documentation/coding-style.rst index 3352b75c7..6ac3a4a0d 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 7eeea7f38..325f27591 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 name of the Pygments (syntax highlighting) style to use. pygments_style = None diff --git a/Documentation/docs.rst b/Documentation/docs.rst index a6e8a59aa..5871961c8 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 000000000..a6915e052 --- /dev/null +++ b/Documentation/documentation-contents.rst @@ -0,0 +1,27 @@ +.. 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` + +.. + The following directive adds the "documentation" class to all of the pages + generated by sphinx. This is not relevant in libcamera nor addressed in the + theme's CSS, since all of the pages here are documentation. It **is** used + to properly format the documentation pages on libcamera.org and so should not + be removed. + +.. rst-class:: documentation diff --git a/Documentation/environment_variables.rst b/Documentation/environment_variables.rst index de434c386..7da9883a8 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 987f43f78..63b050eb7 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 92e2a3732..1ea8c40f4 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 700ec2d33..8368bd4ad 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 25deadefa..cd640563a 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 5aa09e90f..26aea4334 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 ae960d85c..537dce500 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 b96e502d5..85fef76f2 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/meson.build b/Documentation/meson.build index 1ba40fdf6..79135b6f0 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -129,6 +129,7 @@ if sphinx.found() 'conf.py', 'contributing.rst', 'docs.rst', + 'documentation-contents.rst', 'environment_variables.rst', 'guides/application-developer.rst', 'guides/introduction.rst', diff --git a/Documentation/python-bindings.rst b/Documentation/python-bindings.rst index ed9f686b3..947122384 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 0e516b34a..fb4269d03 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 b30331321..9c2a409b1 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 d4274ea6f..2b1ed0957 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; +}