| Message ID | 20250729204228.23217-1-laurent.pinchart@ideasonboard.com |
|---|---|
| Headers | show |
| Series |
|
| Related | show |
Hi Laurent, Quoting Laurent Pinchart (2025-07-29 22:42:23) > 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. Unfortunately this also happens on ubuntu 25.04. So it might not only affect our CI but all the people using ubuntu. To make things worse, you can't update a system-wide python package using pip on ubuntu (I don't know if that differs from debian). So to get the documentation build to run, sphinx must be installed separately. The easiest way to do this is afaik running: sudo apt install pipx pipx install sphinx pipx inject sphinx sphinxcontrib.doxylink meson --reconfigure I know this is basically not our matter, but the error message is not too easy to decode. Can we possibly detect the sphinxcontrib version and supply a message? Or at least mention that in the readme? Best regards, Stefan > > Compared to v1, this series print a nicer error message when the > doxylink module is not found, 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 (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 | 50 +-- > README.rst | 3 +- > 9 files changed, 187 insertions(+), 322 deletions(-) > > > base-commit: 2d5a1367e2b14dab9671270655bbb1702e0826de > -- > Regards, > > Laurent Pinchart >
On Wed, Jul 30, 2025 at 10:34:25AM +0200, Stefan Klug wrote: > Quoting Laurent Pinchart (2025-07-29 22:42:23) > > 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. > > Unfortunately this also happens on ubuntu 25.04. So it might not only > affect our CI but all the people using ubuntu. Thanks for killing my hopes that no other distribution would be affected :-) > To make things worse, you can't update a system-wide python package > using pip on ubuntu (I don't know if that differs from debian). You can install a package with pip that will conflict with a system package with the --break-system-packages option, but you can't update a system package. > So to get the documentation build to run, sphinx must be installed > separately. The easiest way to do this is afaik running: > > sudo apt install pipx > pipx install sphinx > pipx inject sphinx sphinxcontrib.doxylink > meson --reconfigure > > I know this is basically not our matter, but the error message is not > too easy to decode. Can we possibly detect the sphinxcontrib version and > supply a message? Or at least mention that in the readme? I'll try to add at least a version check. > > Compared to v1, this series print a nicer error message when the > > doxylink module is not found, 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 (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 | 50 +-- > > README.rst | 3 +- > > 9 files changed, 187 insertions(+), 322 deletions(-) > > > > > > base-commit: 2d5a1367e2b14dab9671270655bbb1702e0826de