[PATCH v2 1/7] Documentation: Add documentation-contents.rst

Daniel Scally dan.scally at ideasonboard.com
Thu Aug 15 10:29:38 CEST 2024 

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 <laurent.pinchart at ideasonboard.com>
Signed-off-by: Daniel Scally <dan.scally at ideasonboard.com>
---
changes since v1:

	- Formatting
	- Properly added the new file to meson's list of docs_sources
	- Commented the inclusion of the rst-class directive at the end of the
	  new file

 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 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
diff --git a/Documentation/coding-style.rst b/Documentation/coding-style.rst
index 3352b75c..6ac3a4a0 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..325f2759 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 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..a6915e05
--- /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 de434c38..7da9883a 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 5aa09e90..26aea433 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/meson.build b/Documentation/meson.build
index 1ba40fdf..c5736991 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 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;
+}
-- 
2.34.1

More information about the libcamera-devel mailing list