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

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

Message

Laurent Pinchart July 30, 2025, 11:50 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.

Compared to v2, this series print an even nicer error message when the
doxylink module is not found or is too old, which should hopefully help
end users troubleshooting the problem.

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 (3):
  Documentation: Remove unneeded options from Sphinx configuration
  Documentation: Drop documentation author names
  Documentation: Use Sphinx doxylink to generate links to doxygen

 Documentation/Doxyfile-internal.in |  2 +
 Documentation/Doxyfile-public.in   |  2 +
 Documentation/conf.py              | 95 +++++-------------------------
 Documentation/meson.build          | 69 +++++++++++++++-------
 README.rst                         |  3 +-
 5 files changed, 67 insertions(+), 104 deletions(-)


base-commit: 2d5a1367e2b14dab9671270655bbb1702e0826de
prerequisite-patch-id: 91704d112366f8370ab1cf4e34f4a1ab9471e352
--
Regards,

Laurent Pinchart