[PATCH v3 1/7] Documentation: Add documentation-contents.rst
Stefan Klug
stefan.klug at ideasonboard.com
Tue Aug 20 16:47:50 CEST 2024
Hi Dan,
On Tue, Aug 20, 2024 at 11:41:35AM +0100, Dan Scally wrote:
> Hi Stefan
>
> On 20/08/2024 09:06, Stefan Klug wrote:
> > Hi Dan,
> >
> > Thank you for the patch.
> >
> > On Mon, Aug 19, 2024 at 05:09:15PM +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.
> > >
> > > 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.
> > I struggle a bit with adding the documentation-contents.rst to every
> > page even though it is theoretically a property if the "website-theme".
> > I didn't try it out, but would it be possible to set that in the config
> > using rs_prolog? (See
> > https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-rst_prolog)
> >
> > config.py:
> > rst_prolog = """
> > .. include:: documentation-contents.rst
> > """
> >
> > This way we could keep the website specifics out of the content pages
> > (as far as possible) and maybe switch between website and libcamera
> > build using sphinx-build -c ...
>
>
> I think it might make it a bit more awkward unfortunately; it would have to
> be in the website's conf.py and would then unfortunately be present on _all_
> of the website's pages, rather than just the documentation pages, and we'd
> have to figure out a way to remove them from the non-documentation pages
> somehow.
Oh, seems like I'm missing something here. Do I get it right, that the
whole website is generated by sphinx? In that case I can understand the
approach and can't come up with a more elegant solution.
Reviewed-by: Stefan Klug <stefan.klug at ideasonboard.com>
Best regards,
Stefan
>
> >
> >
> > Best regards,
> > Stefan
> >
> > > Reviewed-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
> > > Signed-off-by: Daniel Scally <dan.scally at ideasonboard.com>
> > > ---
> > > Changes since v2:
> > >
> > > - Spaces instead of tabs in meson.build
> > >
> > > 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..79135b6f 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