[RFC,v2] Documentation: Fix documentation generation when subproject

24149 diff mbox series

The paths of the doxygen tag files for sphinxcontrib-doxygen must be
absolute or relative the the current working directory. However, when
libcamera is built as a subproject, the current working directory
is the top-level build directory. Thus the paths for the tag files
will not be correct.

Fix that by using `configure_file()` to generate the final sphinx
configuration with the appropriate paths queried from meson.

Fixes: 0382d215d ("Documentation: Use Sphinx doxylink to generate links to doxygen")
Signed-off-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
changes in v2:
	* variables in alphabetical order
	* import 'fs' module explicitly

v1: https://patchwork.libcamera.org/patch/24044/
---
 Documentation/{conf.py => conf.py.in} |  6 +++---
 Documentation/meson.build             | 17 +++++++++++++++--
 2 files changed, 18 insertions(+), 5 deletions(-)
 rename Documentation/{conf.py => conf.py.in} (95%)

--
2.50.1

Quoting Barnabás Pőcze (2025-08-15 15:39:05)
> The paths of the doxygen tag files for sphinxcontrib-doxygen must be
> absolute or relative the the current working directory. However, when
> libcamera is built as a subproject, the current working directory
> is the top-level build directory. Thus the paths for the tag files
> will not be correct.
> 
> Fix that by using `configure_file()` to generate the final sphinx
> configuration with the appropriate paths queried from meson.
> 
> Fixes: 0382d215d ("Documentation: Use Sphinx doxylink to generate links to doxygen")
> Signed-off-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>
> Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> ---
> changes in v2:
>         * variables in alphabetical order
>         * import 'fs' module explicitly
> 
> v1: https://patchwork.libcamera.org/patch/24044/
> ---
>  Documentation/{conf.py => conf.py.in} |  6 +++---
>  Documentation/meson.build             | 17 +++++++++++++++--
>  2 files changed, 18 insertions(+), 5 deletions(-)
>  rename Documentation/{conf.py => conf.py.in} (95%)
> 
> diff --git a/Documentation/conf.py b/Documentation/conf.py.in
> similarity index 95%
> rename from Documentation/conf.py
> rename to Documentation/conf.py.in
> index f50be60a1..097e579b5 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py.in
> @@ -74,11 +74,11 @@ pygments_style = None
> 
>  doxylink = {
>      'doxy-pub': (
> -        'Documentation/api-html/tagfile.xml',
> +        '@TOP_BUILDDIR@/Documentation/api-html/tagfile.xml',
>          '../api-html/',
>      ),
>      'doxy-int': (
> -        'Documentation/internal-api-html/tagfile.xml',
> +        '@TOP_BUILDDIR@/Documentation/internal-api-html/tagfile.xml',
>          '../internal-api-html/',
>      ),
>  }
> @@ -89,7 +89,7 @@ doxylink = {
>  # a list of builtin themes.
>  #
>  html_theme = 'theme'
> -html_theme_path = ['.']
> +html_theme_path = ['@THEME_DIR@']
> 
>  # Theme options are theme-specific and customize the look and feel of a theme
>  # further.  For a list of options available for each theme, see the
> diff --git a/Documentation/meson.build b/Documentation/meson.build
> index b898ba3a0..10aaf613e 100644
> --- a/Documentation/meson.build
> +++ b/Documentation/meson.build
> @@ -142,11 +142,21 @@ if sphinx.found()
>                .format(mod, version, min_version))
>      endif
> 
> +    sphinx_conf = configure_file(input : 'conf.py.in',
> +                                 output : 'conf.py',
> +                                 configuration : {
> +                                    'THEME_DIR': meson.current_source_dir(),
> +                                    'TOP_BUILDDIR': meson.project_build_root(),
> +                                 })
> +
> +    fs = import('fs')
> +    sphinx_conf_dir = fs.parent(sphinx_conf)
> +
>      docs_sources = [
>          'camera-sensor-model.rst',
>          'code-of-conduct.rst',
>          'coding-style.rst',
> -        'conf.py',
> +        sphinx_conf,

almost caught me - that's a variable not a path ;-)

Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>

>          'contributing.rst',
>          'design/ae.rst',
>          'documentation-contents.rst',
> @@ -171,6 +181,7 @@ if sphinx.found()
> 
>      custom_target('documentation',
>                    command : [sphinx, '-D', release, '-q', '-W', '-b', 'html',
> +                             '-c', sphinx_conf_dir,
>                               meson.current_source_dir(), '@OUTPUT@'],
>                    input : docs_sources,
>                    output : 'html',
> @@ -184,7 +195,9 @@ if sphinx.found()
>                    install_tag : 'doc')
> 
>      custom_target('documentation-linkcheck',
> -                  command : [sphinx, '-W', '-b', 'linkcheck', meson.current_source_dir(), '@OUTPUT@'],
> +                  command : [sphinx, '-W', '-b', 'linkcheck',
> +                             '-c', sphinx_conf_dir,
> +                             meson.current_source_dir(), '@OUTPUT@'],
>                    build_always_stale : true,
>                    input : docs_sources,
>                    output : 'linkcheck')
> --
> 2.50.1