The libcamera documentation comprises two parts: pages generated by
Sphinx into the Documentation/html/ directory within the build tree, and
API reference documentation generated by Doxygen into
Documentation/internal-api-html/ and Documentation/api-html/. The two
parts are generated separately, but link to each other.
From Sphinx to Doxygen, we use the doxylink extension for Sphinx to
generate links to the Doxygen pages corresponding to API elements. The
extension needs to be configured with the paths to the Doxygen
documentation, which are set based on the html/, api-html/ and
internal-api-html/ directories being placed side by side in the same
parent directory.
Furthermore, we also want to link to the API documentation from the
Sphinx toctree. As toctrees can only link to pages within the Sphinx
documents tree (or to http URLs), we have placeholder .rst documents for
api-html and internal-api-html in the Sphinx documentation tree. Those
generate the Documentation/html/internal-api-html/index.html and
Documentation/html/api-html/index.html placeholder files in the build
tree.
The other way around, the API documentation's introduction pagelinks to
Sphinx pages using relative paths. Those paths are hardcoded based on
the api-html/ and internal-api-html/ directories being children of the
html/ directory.
This results in links being broken in different ways in the build tree,
as well as in the installation directory: the toctree links direct to
the placeholder pages within the html/ directory instead of the Doxygen
documentation in sibling directories, and the Doxygen introduction links
to Sphinx are simply broken. When publishing documentation on the
website we work around those issues by overriding conf.py with a custom
version and moving the api-html/ and internal-api-html/ directories to
the html/ directory.
Fixing this is surprisingly difficult. The toctree links can't be
changed to point to a path outside of the Sphinx document tree as this
isn't supported by Sphinx. Using http URLs would link to the
libcamera.org website inside of local documentation, which isn't
acceptable. It may be possible to develop a Sphinx extension to patch
the toctree after it gets parsed, but that would be complex and likely
fragile. Modifying the install path of the Doxygen documentation to
html/api-html/ and html/internal-api-html/ causes issues as the Sphinx
documentation will then overwrite the Doxygen index.html files with the
placeholder indexes. Creating symlinks from html/api-html/ to api-html/
in the installation directory causes similar problems if 'meson install'
is run twice. Creating the symlinks in the build directory (which was
attempted with a custom Sphinx extension) is also a no-go: starting with
meson v1.8.0, installing symlinks to directories causes an exception due
to a bug in meson.
The right solution is probably to investigate usage of the doxysphinx
extension. As that's no small amount of work, let's start with a
non-perfect but simple improvement: configure doxylink based on the
api-html/ and internal-api-html/ directories being children of the
Sphinx html/ documentation, and move those two API documentation
directories to html/ during installation with a post-install script.
This fixes links in the installation directory. Links in the build
directory remain broken, with the toctree links and the links from
Doxygen to Sphinx being broken already, and the links to API elements
through doxylink now being broken too. This is considered as an
acceptable compromise and an overall improvement. The installation
directory is more important, as in the build tree people also have
access to sources. Application developers in particular are less likely
to read documentation from the libcamera build tree, they may not even
have a copy of the libcamera source tree.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Stefan Klug <stefan.klug@ideasonboard.com>
4a9863e053
