[RFC] documentation: Split documentation build task

23972 diff mbox series

Update the CI to split out the documentation task and include a
link-check call.

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

I can't currently get a clean run on the link-check so ... this isn't
mergeable yet - but posting for RFC already so that in the event we
could clean up the linkcheck we could include it to prevent link
regressions creeping in.

I do also like the idea of splitting out the doxygen build anyway so
that documentation failures aren't shown simply in a GCC 12 build...

 .gitlab-ci/build-documentation.sh | 28 ++++++++++++++++++++++++++++
 gitlab-ci.yml                     | 20 ++++++++++++++++++--
 2 files changed, 46 insertions(+), 2 deletions(-)
 create mode 100755 .gitlab-ci/build-documentation.sh

Hi Kieran,

Thank you for the patch.

On Fri, Jul 25, 2025 at 06:51:04PM +0100, Kieran Bingham wrote:
> Update the CI to split out the documentation task and include a
> link-check call.
> 
> Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
> ---
> 
> I can't currently get a clean run on the link-check so ... this isn't
> mergeable yet - but posting for RFC already so that in the event we
> could clean up the linkcheck we could include it to prevent link
> regressions creeping in.
> 
> I do also like the idea of splitting out the doxygen build anyway so
> that documentation failures aren't shown simply in a GCC 12 build...

The documentation is actually built with every compiler, which seems to
be a waste of CPU cycles. I think we should indeed split it, but I'd go
a step further an only build it in a dedicated job.

And now that I wrote that, I've seen a comment on the #freedesktop IRC
channel asking for fewer larger jobs, not more smaller jobs, as spawning
a job on a runner takes a significant amount of resources. Why is
everything always complicated ? :-)

I'll submit a patch to disable documentation building everywhere but in
the gcc 12 job to save CPU cycles. Hopefully that shouldn't be
controversial, and we can then merge this patch (possibly in an adapted
form) on top after discussions.

>  .gitlab-ci/build-documentation.sh | 28 ++++++++++++++++++++++++++++
>  gitlab-ci.yml                     | 20 ++++++++++++++++++--
>  2 files changed, 46 insertions(+), 2 deletions(-)
>  create mode 100755 .gitlab-ci/build-documentation.sh
> 
> diff --git a/.gitlab-ci/build-documentation.sh b/.gitlab-ci/build-documentation.sh
> new file mode 100755
> index 000000000000..33484bd48c0a
> --- /dev/null
> +++ b/.gitlab-ci/build-documentation.sh
> @@ -0,0 +1,28 @@
> +#!/bin/bash
> +
> +# SPDX-License-Identifier: GPL-2.0-or-later
> +# SPDX-FileCopyrightText: © 2025 Kieran Bingham <kieran.bingham@ideasonboard.com>
> +#
> +# Build libcamera Documentation only and perform a link check
> +
> +set -e
> +
> +source "$(dirname "$0")/lib.sh"
> +source "$(dirname "$0")/build-libcamera-common.sh"
> +
> +libcamera_documentation() {
> +	echo "Building libcamera documentation"
> +
> +	meson compile -C build documentation
> +}
> +
> +libcamera_documentation_linkcheck() {
> +	echo "Documentation link-check"
> +
> +	meson compile -C build documentation-linkcheck
> +}
> +
> +run libcamera_install_pkgs collapsed
> +run libcamera_setup collapsed
> +run libcamera_documentation
> +run libcamera_documentation_linkcheck
> diff --git a/gitlab-ci.yml b/gitlab-ci.yml
> index ceb0fd215b89..777456529ac3 100644
> --- a/gitlab-ci.yml
> +++ b/gitlab-ci.yml
> @@ -170,7 +170,6 @@ build-full:debian:12:
>    variables:
>      MESON_OPTIONS: >-
>        ${MESON_ALL_OPTIONS}
> -      -D doc_werror=true
>    parallel:
>      matrix:
>        - ARCH: amd64
> @@ -312,9 +311,26 @@ build-package:cros:
>        dotenv: env
>  
>  # ------------------------------------------------------------------------------
> -# Lint stage - Run checkstyle.py and check merge suitability
> +# Lint stage - Run checkstyle.py and check merge suitability and validate Docs
>  # ------------------------------------------------------------------------------
>  
> +documentation:
> +  extends:
> +    - .fdo.distribution-image@debian
> +    - .libcamera-ci.scripts
> +    - .libcamera-ci.debian:12
> +  stage: lint
> +  needs:
> +    - job: container-debian:12
> +      artifacts: false
> +  script:
> +    - $CI_PROJECT_DIR/.gitlab-ci/build-documentation.sh
> +  variables:
> +    BUILD_TYPE: release
> +    MESON_OPTIONS: >-
> +      ${MESON_ALL_OPTIONS}
> +      -D doc_werror=true
> +
>  lint:
>    extends:
>      - .fdo.distribution-image@debian