[v3,06/10] Documentation: Reorganize toctree

24384 diff mbox series

From: Stefan Klug <stefan.klug@ideasonboard.com>

The libcamera Sphinx documentation contains three toctrees: a main
toctree that contains all documentation pages in a flat hierarchy, and
two hidden toctrees that point to the introduction and API pages. This
architecture is mostly meant to support publishing the documentation on
the libcamera.org website. The process recreates a hybrid documentation
tree mixing content specific to the website and content extracted from
libcamera. The hidden toctrees are used to prevent Sphinx from warning
about unreferenced pages when the documentation is built as part of
libcamera.

This set of hacks work, but produce unorganized documentation in the
build directory, as well as when installed to the system. Furthermore,
they make it difficult to host multiple versions of the libcamera
documentation on the website, which we will eventually want to do as the
API stabilizes. It would be generally better to host on libcamera.org
the documentation built as part of libcamera with the same structure of
documents.

To prepare for that change, reorganize the toctrees in libcamera with
three visible trees: a toctree for users, a toctree for developers, and
a toctree for integrators. Include the public and internal API pages
in the first two trees respectively. This mimics the structure of the
documentation as currently organized on the website. The resulting
documentation becomes easier to navigate in the build and installation
directories.

Signed-off-by: Stefan Klug <stefan.klug@ideasonboard.com>
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
Changes since v2:

- Update commit message

Changes since v1:

- Split the build changes to a separate patch
---
 Documentation/index.rst        | 45 ++++++++++++++++++++--------------
 Documentation/introduction.rst |  6 -----
 2 files changed, 26 insertions(+), 25 deletions(-)

2025. 09. 17. 22:17 keltezéssel, Laurent Pinchart írta:
> From: Stefan Klug <stefan.klug@ideasonboard.com>
> 
> The libcamera Sphinx documentation contains three toctrees: a main
> toctree that contains all documentation pages in a flat hierarchy, and
> two hidden toctrees that point to the introduction and API pages. This
> architecture is mostly meant to support publishing the documentation on
> the libcamera.org website. The process recreates a hybrid documentation
> tree mixing content specific to the website and content extracted from
> libcamera. The hidden toctrees are used to prevent Sphinx from warning
> about unreferenced pages when the documentation is built as part of
> libcamera.
> 
> This set of hacks work, but produce unorganized documentation in the
> build directory, as well as when installed to the system. Furthermore,
> they make it difficult to host multiple versions of the libcamera
> documentation on the website, which we will eventually want to do as the
> API stabilizes. It would be generally better to host on libcamera.org
> the documentation built as part of libcamera with the same structure of
> documents.
> 
> To prepare for that change, reorganize the toctrees in libcamera with
> three visible trees: a toctree for users, a toctree for developers, and
> a toctree for integrators. Include the public and internal API pages
> in the first two trees respectively. This mimics the structure of the
> documentation as currently organized on the website. The resulting
> documentation becomes easier to navigate in the build and installation
> directories.
> 
> Signed-off-by: Stefan Klug <stefan.klug@ideasonboard.com>
> Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> ---
> Changes since v2:
> 
> - Update commit message
> 
> Changes since v1:
> 
> - Split the build changes to a separate patch
> ---

Reviewed-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>


>   Documentation/index.rst        | 45 ++++++++++++++++++++--------------
>   Documentation/introduction.rst |  6 -----
>   2 files changed, 26 insertions(+), 25 deletions(-)
> 
> diff --git a/Documentation/index.rst b/Documentation/index.rst
> index 251112fbdf5f..d55b5ff21464 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -4,28 +4,35 @@
>   
>   .. toctree::
>      :maxdepth: 1
> -   :caption: Contents:
> +   :caption: For Users
>   
> -   Home <self>
> -   Contribute <contributing>
> -   Getting Started <getting-started>
> -
> -   Application Writer's Guide <guides/application-developer>
> -   Camera Sensor Model <camera-sensor-model>
> -   Environment variables <environment_variables>
> +   Introduction <self>
>      Feature Requirements <feature_requirements>
> -   IPA Writer's guide <guides/ipa>
> -   Lens driver requirements <lens_driver_requirements>
> -   libcamera Architecture <libcamera_architecture>
> -   Pipeline Handler Writer's Guide <guides/pipeline-handler>
> +   Application Writer's Guide <guides/application-developer>
>      Python Bindings <python-bindings>
> -   Sensor driver requirements <sensor_driver_requirements>
> -   SoftwareISP Benchmarking <software-isp-benchmarking>
> -   Tracing guide <guides/tracing>
> -
> -   Design document: AE <design/ae>
> +   Environment variables <environment_variables>
> +   Public API <api-html/index>
>   
>   .. toctree::
> -   :hidden:
> +   :maxdepth: 1
> +   :caption: For Developers
> +
> +   Contribute <contributing>
> +   Getting Started <getting-started>
> +   Camera Sensor Model <camera-sensor-model>
> +   IPA Writer's guide <guides/ipa>
> +   libcamera Architecture <libcamera_architecture>
> +   Pipeline Handler Writer's Guide <guides/pipeline-handler>
> +   SoftwareISP Benchmarking <software-isp-benchmarking>
> +   Tracing guide <guides/tracing>
> +   Design document: AE <design/ae>
> +   Internal API <internal-api-html/index>
> +
> +.. toctree::
> +   :maxdepth: 1
> +   :caption: For System Integrators
> +
> +   Lens driver requirements <lens_driver_requirements>
> +   Sensor driver requirements <sensor_driver_requirements>
> +
>   
> -   introduction
> diff --git a/Documentation/introduction.rst b/Documentation/introduction.rst
> index 82aa11a30f33..d76cebd05ee1 100644
> --- a/Documentation/introduction.rst
> +++ b/Documentation/introduction.rst
> @@ -6,12 +6,6 @@
>   Introduction
>   ************
>   
> -.. toctree::
> -   :hidden:
> -
> -   API <api-html/index>
> -   Internal API <internal-api-html/index>
> -
>   What is libcamera?
>   ==================
>