[libcamera-ci,v3,1/2] Split documentation build into separate build step
diff mbox series

Message ID 20260513212613.362445-2-laurent.pinchart@ideasonboard.com
State Superseded
Headers show
Series
  • Deploy documentation to docs.libcamera.org
Related show

Commit Message

Laurent Pinchart May 13, 2026, 9:26 p.m. UTC 
From: Stefan Klug <stefan.klug@ideasonboard.com>

Create a separate build step that builds the docs and merges the html
docs and the api docs into a single docs directory.

Drop the documentation build from the build-full step as it is no longer
needed there.

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

- Don't run libcamera_install_pkgs
- Only build the documentation target
- Install to 'install' instead of '$(pwd)/install' as in other jobs
- Move public and internal API docs to the correct location
- Install with --no-rebuild
- Add meson-logs/ and build.ninja to artifacts (requested by Barnabás)
- Use release build
- Use minimal meson options
---
 .gitlab-ci/build-libcamera-docs.sh | 42 ++++++++++++++++++++++++++++++
 gitlab-ci.yml                      | 33 ++++++++++++++++++++---
 2 files changed, 71 insertions(+), 4 deletions(-)
 create mode 100755 .gitlab-ci/build-libcamera-docs.sh

Comments

Stefan Klug May 14, 2026, 8:08 a.m. UTC | #1 
Hi Laurent,

Thank you for the fixes. I like that we can now build the docs for the
older libcamera versions also :-)

Quoting Laurent Pinchart (2026-05-13 23:26:11)
> From: Stefan Klug <stefan.klug@ideasonboard.com>
> 
> Create a separate build step that builds the docs and merges the html
> docs and the api docs into a single docs directory.
> 
> Drop the documentation build from the build-full step as it is no longer
> needed there.
> 
> Signed-off-by: Stefan Klug <stefan.klug@ideasonboard.com>
> Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>

Looks all good to me.

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

Regards,
Stefan

> ---
> Changes since v2:
> 
> - Don't run libcamera_install_pkgs
> - Only build the documentation target
> - Install to 'install' instead of '$(pwd)/install' as in other jobs
> - Move public and internal API docs to the correct location
> - Install with --no-rebuild
> - Add meson-logs/ and build.ninja to artifacts (requested by Barnabás)
> - Use release build
> - Use minimal meson options
> ---
>  .gitlab-ci/build-libcamera-docs.sh | 42 ++++++++++++++++++++++++++++++
>  gitlab-ci.yml                      | 33 ++++++++++++++++++++---
>  2 files changed, 71 insertions(+), 4 deletions(-)
>  create mode 100755 .gitlab-ci/build-libcamera-docs.sh
> 
> diff --git a/.gitlab-ci/build-libcamera-docs.sh b/.gitlab-ci/build-libcamera-docs.sh
> new file mode 100755
> index 000000000000..26aec0813007
> --- /dev/null
> +++ b/.gitlab-ci/build-libcamera-docs.sh
> @@ -0,0 +1,42 @@
> +#!/bin/bash
> +
> +# SPDX-License-Identifier: GPL-2.0-or-later
> +# SPDX-FileCopyrightText: © 2026 Ideas on Board
> +#
> +# Build libcamera docs and collect them in ./docs
> +
> +set -e
> +
> +source "$(dirname "$0")/lib.sh"
> +source "$(dirname "$0")/build-libcamera-common.sh"
> +
> +libcamera_build_docs() {
> +       echo "Building libcamera docs"
> +
> +       meson compile -C build -j$BUILD_CONCURRENT_JOBS documentation
> +
> +       echo "Installing docs"
> +       rm -rf build/install
> +
> +       meson install -C build \
> +               --destdir install \
> +               --no-rebuild \
> +               --tags doc,doc-internal
> +
> +       local doc_dir=(build/install/usr/local/share/doc/libcamera-*)
> +
> +       rm -rf docs
> +       mv "${doc_dir}/html" docs
> +
> +       # Move the internal and public API directories to the correct location
> +       # in case the libcamera documentation post-install script has not run.
> +       for api in internal-api public-api ; do
> +               if [[ -d "${doc_dir}/${api}" ]] ; then
> +                       rm -rf "docs/${api}"
> +                       mv "${doc_dir}/${api}" docs/
> +               fi
> +       done
> +}
> +
> +run libcamera_setup
> +run libcamera_build_docs collapsed
> diff --git a/gitlab-ci.yml b/gitlab-ci.yml
> index 2b376c5da1ee..278e69079c15 100644
> --- a/gitlab-ci.yml
> +++ b/gitlab-ci.yml
> @@ -209,10 +209,6 @@ build-full:debian:13:
>        - ARCH: amd64
>          CC: gcc-14
>          CXX: g++-14
> -        MESON_OPTIONS: >-
> -          ${MESON_ALL_OPTIONS}
> -          -D documentation=enabled
> -          -D doc_werror=true
>        - ARCH: amd64
>          BUILD_TYPE: release
>          CC: gcc-14
> @@ -301,6 +297,35 @@ build-package:debug:
>        - ARCH: amd64
>        - ARCH: arm64
>  
> +# Build documentation.
> +build-docs:
> +  extends:
> +    - .fdo.distribution-image@debian
> +    - .libcamera-ci.debian:13
> +    - .libcamera-ci.scripts
> +  stage: build
> +  needs:
> +    - job: container-debian:13
> +      artifacts: false
> +  script:
> +    - $CI_PROJECT_DIR/.gitlab-ci/build-libcamera-docs.sh
> +  artifacts:
> +    name: libcamera-docs-${CI_COMMIT_SHA}
> +    when: always
> +    expire_in: 1 week
> +    paths:
> +      - build/meson-logs/
> +      - build/build.ninja
> +      - docs
> +  variables:
> +    BUILD_TYPE: release
> +    MESON_OPTIONS: >-
> +      --auto-features disabled
> +      -D pipelines=[]
> +      -D test=false
> +      -D documentation=enabled
> +      -D doc_werror=true
> +
>  # ------------------------------------------------------------------------------
>  # Lint stage - Run checkstyle.py and check merge suitability
>  # ------------------------------------------------------------------------------
> -- 
> Regards,
> 
> Laurent Pinchart
>
Barnabás Pőcze May 14, 2026, 8:48 a.m. UTC | #2 
2026. 05. 13. 23:26 keltezéssel, Laurent Pinchart írta:
> From: Stefan Klug <stefan.klug@ideasonboard.com>
> 
> Create a separate build step that builds the docs and merges the html
> docs and the api docs into a single docs directory.
> 
> Drop the documentation build from the build-full step as it is no longer
> needed there.
> 
> Signed-off-by: Stefan Klug <stefan.klug@ideasonboard.com>
> Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> ---
> Changes since v2:
> 
> - Don't run libcamera_install_pkgs
> - Only build the documentation target
> - Install to 'install' instead of '$(pwd)/install' as in other jobs
> - Move public and internal API docs to the correct location
> - Install with --no-rebuild
> - Add meson-logs/ and build.ninja to artifacts (requested by Barnabás)
> - Use release build
> - Use minimal meson options
> ---

Looks ok to me.

Reviewed-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>


>   .gitlab-ci/build-libcamera-docs.sh | 42 ++++++++++++++++++++++++++++++
>   gitlab-ci.yml                      | 33 ++++++++++++++++++++---
>   2 files changed, 71 insertions(+), 4 deletions(-)
>   create mode 100755 .gitlab-ci/build-libcamera-docs.sh
> 
> diff --git a/.gitlab-ci/build-libcamera-docs.sh b/.gitlab-ci/build-libcamera-docs.sh
> new file mode 100755
> index 000000000000..26aec0813007
> --- /dev/null
> +++ b/.gitlab-ci/build-libcamera-docs.sh
> @@ -0,0 +1,42 @@
> +#!/bin/bash
> +
> +# SPDX-License-Identifier: GPL-2.0-or-later
> +# SPDX-FileCopyrightText: © 2026 Ideas on Board
> +#
> +# Build libcamera docs and collect them in ./docs
> +
> +set -e
> +
> +source "$(dirname "$0")/lib.sh"
> +source "$(dirname "$0")/build-libcamera-common.sh"
> +
> +libcamera_build_docs() {
> +	echo "Building libcamera docs"
> +
> +	meson compile -C build -j$BUILD_CONCURRENT_JOBS documentation
> +
> +	echo "Installing docs"
> +	rm -rf build/install
> +
> +	meson install -C build \
> +		--destdir install \
> +		--no-rebuild \
> +		--tags doc,doc-internal
> +
> +	local doc_dir=(build/install/usr/local/share/doc/libcamera-*)
> +
> +	rm -rf docs
> +	mv "${doc_dir}/html" docs
> +
> +	# Move the internal and public API directories to the correct location
> +	# in case the libcamera documentation post-install script has not run.
> +	for api in internal-api public-api ; do
> +		if [[ -d "${doc_dir}/${api}" ]] ; then
> +			rm -rf "docs/${api}"
> +			mv "${doc_dir}/${api}" docs/
> +		fi
> +	done
> +}
> +
> +run libcamera_setup
> +run libcamera_build_docs collapsed
> diff --git a/gitlab-ci.yml b/gitlab-ci.yml
> index 2b376c5da1ee..278e69079c15 100644
> --- a/gitlab-ci.yml
> +++ b/gitlab-ci.yml
> @@ -209,10 +209,6 @@ build-full:debian:13:
>         - ARCH: amd64
>           CC: gcc-14
>           CXX: g++-14
> -        MESON_OPTIONS: >-
> -          ${MESON_ALL_OPTIONS}
> -          -D documentation=enabled
> -          -D doc_werror=true
>         - ARCH: amd64
>           BUILD_TYPE: release
>           CC: gcc-14
> @@ -301,6 +297,35 @@ build-package:debug:
>         - ARCH: amd64
>         - ARCH: arm64
>   
> +# Build documentation.
> +build-docs:
> +  extends:
> +    - .fdo.distribution-image@debian
> +    - .libcamera-ci.debian:13
> +    - .libcamera-ci.scripts
> +  stage: build
> +  needs:
> +    - job: container-debian:13
> +      artifacts: false
> +  script:
> +    - $CI_PROJECT_DIR/.gitlab-ci/build-libcamera-docs.sh
> +  artifacts:
> +    name: libcamera-docs-${CI_COMMIT_SHA}
> +    when: always
> +    expire_in: 1 week
> +    paths:
> +      - build/meson-logs/
> +      - build/build.ninja
> +      - docs
> +  variables:
> +    BUILD_TYPE: release
> +    MESON_OPTIONS: >-
> +      --auto-features disabled
> +      -D pipelines=[]
> +      -D test=false
> +      -D documentation=enabled
> +      -D doc_werror=true
> +
>   # ------------------------------------------------------------------------------
>   # Lint stage - Run checkstyle.py and check merge suitability
>   # ------------------------------------------------------------------------------

Patch
diff mbox series 

diff --git a/.gitlab-ci/build-libcamera-docs.sh b/.gitlab-ci/build-libcamera-docs.sh
new file mode 100755
index 000000000000..26aec0813007
--- /dev/null
+++ b/.gitlab-ci/build-libcamera-docs.sh
@@ -0,0 +1,42 @@ 
+#!/bin/bash
+
+# SPDX-License-Identifier: GPL-2.0-or-later
+# SPDX-FileCopyrightText: © 2026 Ideas on Board
+#
+# Build libcamera docs and collect them in ./docs
+
+set -e
+
+source "$(dirname "$0")/lib.sh"
+source "$(dirname "$0")/build-libcamera-common.sh"
+
+libcamera_build_docs() {
+	echo "Building libcamera docs"
+
+	meson compile -C build -j$BUILD_CONCURRENT_JOBS documentation
+
+	echo "Installing docs"
+	rm -rf build/install
+
+	meson install -C build \
+		--destdir install \
+		--no-rebuild \
+		--tags doc,doc-internal
+
+	local doc_dir=(build/install/usr/local/share/doc/libcamera-*)
+
+	rm -rf docs
+	mv "${doc_dir}/html" docs
+
+	# Move the internal and public API directories to the correct location
+	# in case the libcamera documentation post-install script has not run.
+	for api in internal-api public-api ; do
+		if [[ -d "${doc_dir}/${api}" ]] ; then
+			rm -rf "docs/${api}"
+			mv "${doc_dir}/${api}" docs/
+		fi
+	done
+}
+
+run libcamera_setup
+run libcamera_build_docs collapsed
diff --git a/gitlab-ci.yml b/gitlab-ci.yml
index 2b376c5da1ee..278e69079c15 100644
--- a/gitlab-ci.yml
+++ b/gitlab-ci.yml
@@ -209,10 +209,6 @@  build-full:debian:13:
       - ARCH: amd64
         CC: gcc-14
         CXX: g++-14
-        MESON_OPTIONS: >-
-          ${MESON_ALL_OPTIONS}
-          -D documentation=enabled
-          -D doc_werror=true
       - ARCH: amd64
         BUILD_TYPE: release
         CC: gcc-14
@@ -301,6 +297,35 @@  build-package:debug:
       - ARCH: amd64
       - ARCH: arm64
 
+# Build documentation.
+build-docs:
+  extends:
+    - .fdo.distribution-image@debian
+    - .libcamera-ci.debian:13
+    - .libcamera-ci.scripts
+  stage: build
+  needs:
+    - job: container-debian:13
+      artifacts: false
+  script:
+    - $CI_PROJECT_DIR/.gitlab-ci/build-libcamera-docs.sh
+  artifacts:
+    name: libcamera-docs-${CI_COMMIT_SHA}
+    when: always
+    expire_in: 1 week
+    paths:
+      - build/meson-logs/
+      - build/build.ninja
+      - docs
+  variables:
+    BUILD_TYPE: release
+    MESON_OPTIONS: >-
+      --auto-features disabled
+      -D pipelines=[]
+      -D test=false
+      -D documentation=enabled
+      -D doc_werror=true
+
 # ------------------------------------------------------------------------------
 # Lint stage - Run checkstyle.py and check merge suitability
 # ------------------------------------------------------------------------------