[0/4] Documentation: Use doxylink to generate Sphinx-to-Doxygen links
mbox series

Message ID 20250727015720.6867-1-laurent.pinchart@ideasonboard.com
Headers show
Series
  • Documentation: Use doxylink to generate Sphinx-to-Doxygen links
Related show

Message

Laurent Pinchart July 27, 2025, 1:57 a.m. UTC 
Hello,

This patch series fixes a long-standing issue in the libcamera Sphinx
documentation: links from Sphinx to Doxygen.

While links between Sphinx pages are generated by Sphinx, and links
within the API documentation are generated by Doxygen, links from Sphinx
to Doxygen are currently manual, and point to the libcamera.org website.
This causes links to regularly break, and prevents testing documentation
builds fully offline.

The doxylink Sphinx extension module comes to the rescue. It allows
referencing the Doxygen documentation from within Sphinx documents,
using a custom role.

The series starts with two small cleanups of the Sphinx configuration in
patches 1/4 and 2/4. Patch 3/4 then enables doxylink in the build system
and in the Sphinx configuration, and patch 4/4 replaces manual links.

The main drawback with this solution is the new dependency on doxylink.
The module is packaged by Debian, but the version in Bookworm is not
compatible with the Sphinx version shipped by the same distribution
(doxylink prior to v1.6.1 used an API that got removed in Sphinx 2.0,
and Bookworm ships doxylink v1.5.1 and Sphinx v5.3.0, which makes me
wonder how this got tested). The issue is fixed in Debian 13, and the
doxylink module can be installed from PyPI in the meantime.

I've posted a series to update the CI containers with the new
dependency, see [1]. With those patches applied, this series passes CI.

[1] https://patchwork.libcamera.org/project/libcamera/list/?series=5339.

Laurent Pinchart (4):
  Documentation: Remove unneeded options from Sphinx configuration
  Documentation: Drop documentation author names
  Documentation: Use Sphinx doxylink to generate links to doxygen
  Documentation: Replace links to Doxygen documentation with doxylink

 Documentation/Doxyfile-internal.in            |   2 +
 Documentation/Doxyfile-public.in              |   2 +
 Documentation/conf.py                         |  95 +-----
 Documentation/environment_variables.rst       |   2 +-
 .../guides/application-developer.rst          |  30 +-
 Documentation/guides/pipeline-handler.rst     | 312 +++++++-----------
 Documentation/libcamera_architecture.rst      |  13 +-
 Documentation/meson.build                     |  48 +--
 README.rst                                    |   3 +-
 9 files changed, 185 insertions(+), 322 deletions(-)


base-commit: 16da4892ed9de3ac8f84dfd0d1761022656af376
--
Regards,

Laurent Pinchart