Documentation: Reorganize toctree

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>
Reviewed-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>

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

Documentation/introduction.rst

@@ -6,12 +6,6 @@
 Introduction
 ************
 
-.. toctree::
-   :hidden:
-
-   API <api-html/index>
-   Internal API <internal-api-html/index>
-
 What is libcamera?
 ==================