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>
The introduction.rst file contains the introduction to the libcamera
documentation. Rename the section from "Documentation" to
"Introduction".
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Daniel Scally <dan.scally@ideasonboard.com>
The local table of contents from the introduction page doesn't provide
much navigation value as the page is short. It also stands out, as no
other page has a local table of contents. Drop it, we will reintroduce
local tables of contents more globally if needed later.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Daniel Scally <dan.scally@ideasonboard.com>
Mimicking the existing api-html placeholder, add a placeholder for the
internal version of the Doxygen generated API documentation so that the
website can generate hyperlinks to it properly.
Signed-off-by: Daniel Scally <dan.scally@ideasonboard.com>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
docs.rst is the landing page for the documentation from the libcamera
website, but isn't particularly introductory. Move much of the content
from guides/introduction.rst to docs.rst, which will serve as the new
introductory page. Remove guides/introduction.rst.
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Daniel Scally <dan.scally@ideasonboard.com>
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Stefan Klug
Laurent Pinchart
Daniel Scally