[PATCH 1/7] Documentation: Add documentation-contents.rst
Laurent Pinchart
laurent.pinchart at ideasonboard.com
Thu Aug 15 00:31:30 CEST 2024
On Wed, Aug 14, 2024 at 11:22:53PM +0100, Daniel Scally wrote:
> On 14/08/2024 23:18, Laurent Pinchart wrote:
> > 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.
I suspected so, but there's no documentation class in the css defined at
this point, is there ? That's why I asked if this belong to a different
patch.
As for having the class in this file, it's a bit of a hack, but I can
live with it.
> > 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;
> >> +}
--
Regards,
Laurent Pinchart
More information about the libcamera-devel
mailing list