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

24044 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.

Signed-off-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>
---
 Documentation/{conf.py => conf.py.in} |  6 +++---
 Documentation/meson.build             | 16 ++++++++++++++--
 2 files changed, 17 insertions(+), 5 deletions(-)
 rename Documentation/{conf.py => conf.py.in} (95%)

Hi Barnabás,

Thank you for the patch.

On Thu, Jul 31, 2025 at 02:32:47PM +0200, Barnabás Pőcze wrote:
> 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.
> 
> Signed-off-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>
> ---
>  Documentation/{conf.py => conf.py.in} |  6 +++---
>  Documentation/meson.build             | 16 ++++++++++++++--
>  2 files changed, 17 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/',
>      ),
>  }

I was hoping we could override this on the command line with Sphinx's -D
option, using something like

doxylink = {
    'doxy-pub': (
        f'{top_builddir}Documentation/api-html/tagfile.xml',
        '../api-html/',
    ),
    'doxy-int': (
        f'{top_builddir}Documentation/internal-api-html/tagfile.xml',
        '../internal-api-html/',
    ),
}

and setting -D top_builddir=... but Sphinx apparently restricts -D to
override known config options, not arbitrary variables :-(

> @@ -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..0710084fe 100644
> --- a/Documentation/meson.build
> +++ b/Documentation/meson.build
> @@ -142,11 +142,20 @@ if sphinx.found()
>                .format(mod, version, min_version))
>      endif
>  
> +    sphinx_conf = configure_file(input : 'conf.py.in',
> +                                 output : 'conf.py',
> +                                 configuration : {
> +                                    'TOP_BUILDDIR': meson.project_build_root(),
> +                                    'THEME_DIR': meson.current_source_dir(),

Alphabetical order ?

> +                                 })
> +
> +    sphinx_conf_dir = fs.parent(sphinx_conf)

Please import the fs module here. It's imported in
src/gstreamer/meson.build, and I'd rather not rely on that here.

> +
>      docs_sources = [
>          'camera-sensor-model.rst',
>          'code-of-conduct.rst',
>          'coding-style.rst',
> -        'conf.py',
> +        sphinx_conf,
>          'contributing.rst',
>          'design/ae.rst',
>          'documentation-contents.rst',
> @@ -171,6 +180,7 @@ if sphinx.found()
>  
>      custom_target('documentation',
>                    command : [sphinx, '-D', release, '-q', '-W', '-b', 'html',
> +                             '--conf-dir', sphinx_conf_dir,
>                               meson.current_source_dir(), '@OUTPUT@'],
>                    input : docs_sources,
>                    output : 'html',
> @@ -184,7 +194,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',
> +                             '--conf-dir', sphinx_conf_dir,
> +                             meson.current_source_dir(), '@OUTPUT@'],

linkcheck will also benefit from overriding paths in doxylink (see my
separate e-mail on that subject), so this patch comes handy.

With the above comments addressed,

Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>

>                    build_always_stale : true,
>                    input : docs_sources,
>                    output : 'linkcheck')