[v3,3/3] Documentation: Use Sphinx doxylink to generate links to doxygen
diff mbox series

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

Commit Message

Laurent Pinchart July 30, 2025, 11:50 a.m. UTC 
The libcamera Sphinx documentation needs to link to the API
documentation generated by Doxygen. The links currently point to the
documentation hosted on the official https://libcamera.org/ website.
This causes multiple issues:

- Doxygen generates URLs with MD5 hashes of function signatures, making
  the link targets unstable.

- When testing documentation builds that include API changes, links to
  new API elements will be broken.

- The generated documentation can't be browsed offline.

Fix this by using the Sphinx doxylink extension. This allows specifying
link targets as class and function names, with the link being
automatically generated using the same MD5 hashing as Doxygen. The root
of the link target is configured in a central location, which defaults
to the build directory and can be overridden to point to the libcamera
website when pushing the documentation.

This commit only introduces the infrastructure to use doxylink. Manual
links will be replaced separately.

Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
Changes since v2:

- Manually check the doxylink version

Changes since v1:

- Add sphinxcontrib.doxylink to py_modules
---
 Documentation/Doxyfile-internal.in |  2 +
 Documentation/Doxyfile-public.in   |  2 +
 Documentation/conf.py              | 13 +++++-
 Documentation/meson.build          | 69 ++++++++++++++++++++----------
 README.rst                         |  3 +-
 5 files changed, 65 insertions(+), 24 deletions(-)

Comments

Stefan Klug July 30, 2025, 1:36 p.m. UTC | #1 
Hi Laurent,

Thank you for the patch.

Quoting Laurent Pinchart (2025-07-30 13:50:44)
> The libcamera Sphinx documentation needs to link to the API
> documentation generated by Doxygen. The links currently point to the
> documentation hosted on the official https://libcamera.org/ website.
> This causes multiple issues:
> 
> - Doxygen generates URLs with MD5 hashes of function signatures, making
>   the link targets unstable.
> 
> - When testing documentation builds that include API changes, links to
>   new API elements will be broken.
> 
> - The generated documentation can't be browsed offline.
> 
> Fix this by using the Sphinx doxylink extension. This allows specifying
> link targets as class and function names, with the link being
> automatically generated using the same MD5 hashing as Doxygen. The root
> of the link target is configured in a central location, which defaults
> to the build directory and can be overridden to point to the libcamera
> website when pushing the documentation.
> 
> This commit only introduces the infrastructure to use doxylink. Manual
> links will be replaced separately.
> 
> Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> ---
> Changes since v2:
> 
> - Manually check the doxylink version
> 
> Changes since v1:
> 
> - Add sphinxcontrib.doxylink to py_modules
> ---
>  Documentation/Doxyfile-internal.in |  2 +
>  Documentation/Doxyfile-public.in   |  2 +
>  Documentation/conf.py              | 13 +++++-
>  Documentation/meson.build          | 69 ++++++++++++++++++++----------
>  README.rst                         |  3 +-
>  5 files changed, 65 insertions(+), 24 deletions(-)
> 
> diff --git a/Documentation/Doxyfile-internal.in b/Documentation/Doxyfile-internal.in
> index 5343bc2b131c..a422bb0719da 100644
> --- a/Documentation/Doxyfile-internal.in
> +++ b/Documentation/Doxyfile-internal.in
> @@ -3,6 +3,8 @@
>  @INCLUDE_PATH          = @TOP_BUILDDIR@/Documentation
>  @INCLUDE               = Doxyfile-common
>  
> +GENERATE_TAGFILE       = @TOP_BUILDDIR@/Documentation/internal-api-html/tagfile.xml
> +
>  HIDE_UNDOC_CLASSES     = NO
>  HIDE_UNDOC_MEMBERS     = NO
>  HTML_OUTPUT            = internal-api-html
> diff --git a/Documentation/Doxyfile-public.in b/Documentation/Doxyfile-public.in
> index 36bb57584a07..c3a8b0dd003a 100644
> --- a/Documentation/Doxyfile-public.in
> +++ b/Documentation/Doxyfile-public.in
> @@ -3,6 +3,8 @@
>  @INCLUDE_PATH          = @TOP_BUILDDIR@/Documentation
>  @INCLUDE               = Doxyfile-common
>  
> +GENERATE_TAGFILE       = @TOP_BUILDDIR@/Documentation/api-html/tagfile.xml
> +
>  HIDE_UNDOC_CLASSES     = YES
>  HIDE_UNDOC_MEMBERS     = YES
>  HTML_OUTPUT            = api-html
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 870937289eb4..f50be60a1559 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -37,7 +37,8 @@ author = 'The libcamera documentation authors'
>  # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
>  # ones.
>  extensions = [
> -    'sphinx.ext.graphviz'
> +    'sphinx.ext.graphviz',
> +    'sphinxcontrib.doxylink',
>  ]
>  
>  graphviz_output_format = 'svg'
> @@ -71,6 +72,16 @@ exclude_patterns = [
>  # The name of the Pygments (syntax highlighting) style to use.
>  pygments_style = None
>  
> +doxylink = {
> +    'doxy-pub': (
> +        'Documentation/api-html/tagfile.xml',
> +        '../api-html/',
> +    ),
> +    'doxy-int': (
> +        'Documentation/internal-api-html/tagfile.xml',
> +        '../internal-api-html/',
> +    ),
> +}
>  
>  # -- Options for HTML output -------------------------------------------------
>  
> diff --git a/Documentation/meson.build b/Documentation/meson.build
> index 3afdcc1a87af..b898ba3a0b7e 100644
> --- a/Documentation/meson.build
> +++ b/Documentation/meson.build
> @@ -81,16 +81,16 @@ if doxygen.found() and dot.found()
>                                   '@INPUT@',
>                               ])
>  
> -    custom_target('doxygen-public',
> -                  input : [
> -                      doxyfile,
> -                      doxyfile_common,
> -                  ],
> -                  output : 'api-html',
> -                  command : [doxygen, doxyfile],
> -                  install : true,
> -                  install_dir : doc_install_dir,
> -                  install_tag : 'doc')
> +    doxygen_public = custom_target('doxygen-public',
> +                                   input : [
> +                                       doxyfile,
> +                                       doxyfile_common,
> +                                   ],
> +                                   output : 'api-html',
> +                                   command : [doxygen, doxyfile],
> +                                   install : true,
> +                                   install_dir : doc_install_dir,
> +                                   install_tag : 'doc')
>  
>      # This is the internal documentation, which hard-codes a list of directories
>      # to parse in its doxyfile.
> @@ -99,18 +99,18 @@ if doxygen.found() and dot.found()
>                                output : 'Doxyfile-internal',
>                                configuration : cdata)
>  
> -    custom_target('doxygen-internal',
> -                  input : [
> -                      doxyfile,
> -                      doxyfile_common,
> -                      doxygen_public_input,
> -                      doxygen_internal_input,
> -                  ],
> -                  output : 'internal-api-html',
> -                  command : [doxygen, doxyfile],
> -                  install : true,
> -                  install_dir : doc_install_dir,
> -                  install_tag : 'doc-internal')
> +    doxygen_internal = custom_target('doxygen-internal',
> +                                     input : [
> +                                         doxyfile,
> +                                         doxyfile_common,
> +                                         doxygen_public_input,
> +                                         doxygen_internal_input,
> +                                     ],
> +                                     output : 'internal-api-html',
> +                                     command : [doxygen, doxyfile],
> +                                     install : true,
> +                                     install_dir : doc_install_dir,
> +                                     install_tag : 'doc-internal')
>  endif
>  
>  #
> @@ -121,6 +121,27 @@ sphinx = find_program('sphinx-build-3', 'sphinx-build',
>                        required : get_option('documentation'))
>  
>  if sphinx.found()
> +    # Many distributions do not provide a recent-enough version of the doxylink
> +    # module. This results in a build error with a cryptic message. Check the
> +    # version manually and print clear error messages.
> +    py_mod = import('python')
> +    py3 = py_mod.find_installation('python3')
> +
> +    mod = 'sphinxcontrib.doxylink'
> +    min_version = '>=1.6.1'
> +    version = run_command(py3, '-c',
> +                          'import @0@ ; print(@0@.__version__)'.format(mod),
> +                          check : false).stdout().strip()
> +
> +    if version == ''
> +        error('@0@ module not found'.format(mod))
> +    endif
> +
> +    if not version.version_compare(min_version)
> +        error('@0@ module v@1@ is too old, @2@ is needed'
> +              .format(mod, version, min_version))
> +    endif

Ugh that is harder than it should be. Thanks for the error message...

Reviewed-by: Stefan Klug <stefan.klug@ideasonboard.com>

> +
>      docs_sources = [
>          'camera-sensor-model.rst',
>          'code-of-conduct.rst',
> @@ -154,6 +175,10 @@ if sphinx.found()
>                    input : docs_sources,
>                    output : 'html',
>                    build_by_default : true,
> +                  depends : [
> +                      doxygen_public,
> +                      doxygen_internal,
> +                  ],
>                    install : true,
>                    install_dir : doc_install_dir,
>                    install_tag : 'doc')
> diff --git a/README.rst b/README.rst
> index e2a6e275895e..e9a7dd82de74 100644
> --- a/README.rst
> +++ b/README.rst
> @@ -67,7 +67,8 @@ for device hotplug enumeration: [optional]
>          libudev-dev
>  
>  for documentation: [optional]
> -        python3-sphinx doxygen graphviz texlive-latex-extra
> +        doxygen graphviz python3-sphinx python3-sphinxcontrib.doxylink (>= 1.6.1)
> +        texlive-latex-extra
>  
>  for gstreamer: [optional]
>          libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev
> -- 
> Regards,
> 
> Laurent Pinchart
>

Patch
diff mbox series 

diff --git a/Documentation/Doxyfile-internal.in b/Documentation/Doxyfile-internal.in
index 5343bc2b131c..a422bb0719da 100644
--- a/Documentation/Doxyfile-internal.in
+++ b/Documentation/Doxyfile-internal.in
@@ -3,6 +3,8 @@ 
 @INCLUDE_PATH          = @TOP_BUILDDIR@/Documentation
 @INCLUDE               = Doxyfile-common
 
+GENERATE_TAGFILE       = @TOP_BUILDDIR@/Documentation/internal-api-html/tagfile.xml
+
 HIDE_UNDOC_CLASSES     = NO
 HIDE_UNDOC_MEMBERS     = NO
 HTML_OUTPUT            = internal-api-html
diff --git a/Documentation/Doxyfile-public.in b/Documentation/Doxyfile-public.in
index 36bb57584a07..c3a8b0dd003a 100644
--- a/Documentation/Doxyfile-public.in
+++ b/Documentation/Doxyfile-public.in
@@ -3,6 +3,8 @@ 
 @INCLUDE_PATH          = @TOP_BUILDDIR@/Documentation
 @INCLUDE               = Doxyfile-common
 
+GENERATE_TAGFILE       = @TOP_BUILDDIR@/Documentation/api-html/tagfile.xml
+
 HIDE_UNDOC_CLASSES     = YES
 HIDE_UNDOC_MEMBERS     = YES
 HTML_OUTPUT            = api-html
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 870937289eb4..f50be60a1559 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -37,7 +37,8 @@  author = 'The libcamera documentation authors'
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.graphviz'
+    'sphinx.ext.graphviz',
+    'sphinxcontrib.doxylink',
 ]
 
 graphviz_output_format = 'svg'
@@ -71,6 +72,16 @@  exclude_patterns = [
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = None
 
+doxylink = {
+    'doxy-pub': (
+        'Documentation/api-html/tagfile.xml',
+        '../api-html/',
+    ),
+    'doxy-int': (
+        'Documentation/internal-api-html/tagfile.xml',
+        '../internal-api-html/',
+    ),
+}
 
 # -- Options for HTML output -------------------------------------------------
 
diff --git a/Documentation/meson.build b/Documentation/meson.build
index 3afdcc1a87af..b898ba3a0b7e 100644
--- a/Documentation/meson.build
+++ b/Documentation/meson.build
@@ -81,16 +81,16 @@  if doxygen.found() and dot.found()
                                  '@INPUT@',
                              ])
 
-    custom_target('doxygen-public',
-                  input : [
-                      doxyfile,
-                      doxyfile_common,
-                  ],
-                  output : 'api-html',
-                  command : [doxygen, doxyfile],
-                  install : true,
-                  install_dir : doc_install_dir,
-                  install_tag : 'doc')
+    doxygen_public = custom_target('doxygen-public',
+                                   input : [
+                                       doxyfile,
+                                       doxyfile_common,
+                                   ],
+                                   output : 'api-html',
+                                   command : [doxygen, doxyfile],
+                                   install : true,
+                                   install_dir : doc_install_dir,
+                                   install_tag : 'doc')
 
     # This is the internal documentation, which hard-codes a list of directories
     # to parse in its doxyfile.
@@ -99,18 +99,18 @@  if doxygen.found() and dot.found()
                               output : 'Doxyfile-internal',
                               configuration : cdata)
 
-    custom_target('doxygen-internal',
-                  input : [
-                      doxyfile,
-                      doxyfile_common,
-                      doxygen_public_input,
-                      doxygen_internal_input,
-                  ],
-                  output : 'internal-api-html',
-                  command : [doxygen, doxyfile],
-                  install : true,
-                  install_dir : doc_install_dir,
-                  install_tag : 'doc-internal')
+    doxygen_internal = custom_target('doxygen-internal',
+                                     input : [
+                                         doxyfile,
+                                         doxyfile_common,
+                                         doxygen_public_input,
+                                         doxygen_internal_input,
+                                     ],
+                                     output : 'internal-api-html',
+                                     command : [doxygen, doxyfile],
+                                     install : true,
+                                     install_dir : doc_install_dir,
+                                     install_tag : 'doc-internal')
 endif
 
 #
@@ -121,6 +121,27 @@  sphinx = find_program('sphinx-build-3', 'sphinx-build',
                       required : get_option('documentation'))
 
 if sphinx.found()
+    # Many distributions do not provide a recent-enough version of the doxylink
+    # module. This results in a build error with a cryptic message. Check the
+    # version manually and print clear error messages.
+    py_mod = import('python')
+    py3 = py_mod.find_installation('python3')
+
+    mod = 'sphinxcontrib.doxylink'
+    min_version = '>=1.6.1'
+    version = run_command(py3, '-c',
+                          'import @0@ ; print(@0@.__version__)'.format(mod),
+                          check : false).stdout().strip()
+
+    if version == ''
+        error('@0@ module not found'.format(mod))
+    endif
+
+    if not version.version_compare(min_version)
+        error('@0@ module v@1@ is too old, @2@ is needed'
+              .format(mod, version, min_version))
+    endif
+
     docs_sources = [
         'camera-sensor-model.rst',
         'code-of-conduct.rst',
@@ -154,6 +175,10 @@  if sphinx.found()
                   input : docs_sources,
                   output : 'html',
                   build_by_default : true,
+                  depends : [
+                      doxygen_public,
+                      doxygen_internal,
+                  ],
                   install : true,
                   install_dir : doc_install_dir,
                   install_tag : 'doc')
diff --git a/README.rst b/README.rst
index e2a6e275895e..e9a7dd82de74 100644
--- a/README.rst
+++ b/README.rst
@@ -67,7 +67,8 @@  for device hotplug enumeration: [optional]
         libudev-dev
 
 for documentation: [optional]
-        python3-sphinx doxygen graphviz texlive-latex-extra
+        doxygen graphviz python3-sphinx python3-sphinxcontrib.doxylink (>= 1.6.1)
+        texlive-latex-extra
 
 for gstreamer: [optional]
         libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev