[v2,1/2] Split documentation build into separate build step
diff mbox series

Message ID 20260511134817.2841886-2-stefan.klug@ideasonboard.com
State Superseded
Headers show
Series
  • Deploy documentation to docs.libcamera.org
Related show

Commit Message

Stefan Klug May 11, 2026, 1:48 p.m. UTC 
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>

---

Changes in v2:
- Fixed copyright
- Fixed comments and build message
- Build debug for now, as the upstream release build is broken
- Collect docs from a temporary install dir
---
 .gitlab-ci/build-libcamera-docs.sh | 35 ++++++++++++++++++++++++++++++
 gitlab-ci.yml                      | 30 +++++++++++++++++++++----
 2 files changed, 61 insertions(+), 4 deletions(-)
 create mode 100755 .gitlab-ci/build-libcamera-docs.sh

Comments

Barnabás Pőcze May 12, 2026, 9:02 a.m. UTC | #1 
2026. 05. 11. 15:48 keltezéssel, Stefan Klug írta:
> 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.

(Alternatively the deploy job could use the (documentation) artifacts of that build job,
  and then this separate one would not be necessary.)


> 
> Signed-off-by: Stefan Klug <stefan.klug@ideasonboard.com>
> 
> ---
> 
> Changes in v2:
> - Fixed copyright
> - Fixed comments and build message
> - Build debug for now, as the upstream release build is broken
> - Collect docs from a temporary install dir
> ---
>   .gitlab-ci/build-libcamera-docs.sh | 35 ++++++++++++++++++++++++++++++
>   gitlab-ci.yml                      | 30 +++++++++++++++++++++----
>   2 files changed, 61 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..cccb5bad9cb5
> --- /dev/null
> +++ b/.gitlab-ci/build-libcamera-docs.sh
> @@ -0,0 +1,35 @@
> +#!/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"
> +
> +	# Fixme: This should only build the documentation, but as we can't use
> +	# the doc tag for installation we need to build everything.
> +	meson compile -C build -j$BUILD_CONCURRENT_JOBS
> +
> +	echo "Installing docs"
> +	rm -rf install
> +	mkdir install
> +
> +	# Fixme: This should use --tags doc,doc-internal, but the installation
> +	# mechanics are broken and need to be fixed in libcamera. Install the
> +	# whole project for now.

For my interest, are there are specific failed jobs that exhibit the installation issue?
Or could we add a bit more info here, or maybe better, open an issue on gitlab?


> +	meson install -C build --destdir $(pwd)/install
> +
> +	rm -rf docs
> +	mv install/usr/local/share/doc/libcamera-*/html docs
> +}
> +
> +run libcamera_install_pkgs
> +run libcamera_setup
> +run libcamera_build_docs collapsed
> diff --git a/gitlab-ci.yml b/gitlab-ci.yml
> index f887e3b6c221..7c5e59de30a1 100644
> --- a/gitlab-ci.yml
> +++ b/gitlab-ci.yml
> @@ -229,10 +229,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
>           CC: clang
>           CXX: clang++
> @@ -302,6 +298,32 @@ 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:
> +      - docs

Could we add
   - build/meson-logs/
   - build/build.ninja
?

I find these two quite useful in diagnosing build issues, so I think
they are worth saving.


> +  variables:
> +    # Fixme: Switch to release build as soon as the build issues are fixed.
> +    BUILD_TYPE: debug
> +    MESON_OPTIONS: >-
> +      ${MESON_ALL_OPTIONS}
> +      -D documentation=enabled
> +      -D doc_werror=true
> +
>   # ------------------------------------------------------------------------------
>   # Lint stage - Run checkstyle.py and check merge suitability
>   # ------------------------------------------------------------------------------
Stefan Klug May 12, 2026, 10:30 a.m. UTC | #2 
Quoting Barnabás Pőcze (2026-05-12 11:02:43)
> 2026. 05. 11. 15:48 keltezéssel, Stefan Klug írta:
> > 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.
> 
> (Alternatively the deploy job could use the (documentation) artifacts of that build job,
>   and then this separate one would not be necessary.)

Actually I like the fact that the documentation build is ideally
independent of the rest of the build.

> 
> 
> > 
> > Signed-off-by: Stefan Klug <stefan.klug@ideasonboard.com>
> > 
> > ---
> > 
> > Changes in v2:
> > - Fixed copyright
> > - Fixed comments and build message
> > - Build debug for now, as the upstream release build is broken
> > - Collect docs from a temporary install dir
> > ---
> >   .gitlab-ci/build-libcamera-docs.sh | 35 ++++++++++++++++++++++++++++++
> >   gitlab-ci.yml                      | 30 +++++++++++++++++++++----
> >   2 files changed, 61 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..cccb5bad9cb5
> > --- /dev/null
> > +++ b/.gitlab-ci/build-libcamera-docs.sh
> > @@ -0,0 +1,35 @@
> > +#!/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"
> > +
> > +     # Fixme: This should only build the documentation, but as we can't use
> > +     # the doc tag for installation we need to build everything.
> > +     meson compile -C build -j$BUILD_CONCURRENT_JOBS
> > +
> > +     echo "Installing docs"
> > +     rm -rf install
> > +     mkdir install
> > +
> > +     # Fixme: This should use --tags doc,doc-internal, but the installation
> > +     # mechanics are broken and need to be fixed in libcamera. Install the
> > +     # whole project for now.
> 
> For my interest, are there are specific failed jobs that exhibit the installation issue?
> Or could we add a bit more info here, or maybe better, open an issue on gitlab?
> 

I created an issue here:
https://gitlab.freedesktop.org/camera/libcamera/-/work_items/333

> 
> > +     meson install -C build --destdir $(pwd)/install
> > +
> > +     rm -rf docs
> > +     mv install/usr/local/share/doc/libcamera-*/html docs
> > +}
> > +
> > +run libcamera_install_pkgs
> > +run libcamera_setup
> > +run libcamera_build_docs collapsed
> > diff --git a/gitlab-ci.yml b/gitlab-ci.yml
> > index f887e3b6c221..7c5e59de30a1 100644
> > --- a/gitlab-ci.yml
> > +++ b/gitlab-ci.yml
> > @@ -229,10 +229,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
> >           CC: clang
> >           CXX: clang++
> > @@ -302,6 +298,32 @@ 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:
> > +      - docs
> 
> Could we add
>    - build/meson-logs/
>    - build/build.ninja
> ?
> 
> I find these two quite useful in diagnosing build issues, so I think
> they are worth saving.

Oh I never looked at these. Sure we can add them.

Best regards,
Stefan

> 
> 
> > +  variables:
> > +    # Fixme: Switch to release build as soon as the build issues are fixed.
> > +    BUILD_TYPE: debug
> > +    MESON_OPTIONS: >-
> > +      ${MESON_ALL_OPTIONS}
> > +      -D documentation=enabled
> > +      -D doc_werror=true
> > +
> >   # ------------------------------------------------------------------------------
> >   # Lint stage - Run checkstyle.py and check merge suitability
> >   # ------------------------------------------------------------------------------
>
Laurent Pinchart May 12, 2026, 3:05 p.m. UTC | #3 
On Tue, May 12, 2026 at 12:30:57PM +0200, Stefan Klug wrote:
> Quoting Barnabás Pőcze (2026-05-12 11:02:43)
> > 2026. 05. 11. 15:48 keltezéssel, Stefan Klug írta:
> > > 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.
> > 
> > (Alternatively the deploy job could use the (documentation) artifacts of that build job,
> >   and then this separate one would not be necessary.)
> 
> Actually I like the fact that the documentation build is ideally
> independent of the rest of the build.

I would as well, if it wasn't for the fact that starting a runner for a
short job incurs a bit overhead. I think it's OK for now, but we may
want to optimize that later.

> > > Signed-off-by: Stefan Klug <stefan.klug@ideasonboard.com>
> > > 
> > > ---
> > > 
> > > Changes in v2:
> > > - Fixed copyright
> > > - Fixed comments and build message
> > > - Build debug for now, as the upstream release build is broken
> > > - Collect docs from a temporary install dir
> > > ---
> > >   .gitlab-ci/build-libcamera-docs.sh | 35 ++++++++++++++++++++++++++++++
> > >   gitlab-ci.yml                      | 30 +++++++++++++++++++++----
> > >   2 files changed, 61 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..cccb5bad9cb5
> > > --- /dev/null
> > > +++ b/.gitlab-ci/build-libcamera-docs.sh
> > > @@ -0,0 +1,35 @@
> > > +#!/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"
> > > +
> > > +     # Fixme: This should only build the documentation, but as we can't use
> > > +     # the doc tag for installation we need to build everything.
> > > +     meson compile -C build -j$BUILD_CONCURRENT_JOBS
> > > +
> > > +     echo "Installing docs"
> > > +     rm -rf install
> > > +     mkdir install
> > > +
> > > +     # Fixme: This should use --tags doc,doc-internal, but the installation
> > > +     # mechanics are broken and need to be fixed in libcamera. Install the
> > > +     # whole project for now.
> > 
> > For my interest, are there are specific failed jobs that exhibit the installation issue?
> > Or could we add a bit more info here, or maybe better, open an issue on gitlab?
> 
> I created an issue here:
> https://gitlab.freedesktop.org/camera/libcamera/-/work_items/333

I'll try to fix that tonight.

> > > +     meson install -C build --destdir $(pwd)/install
> > > +
> > > +     rm -rf docs
> > > +     mv install/usr/local/share/doc/libcamera-*/html docs
> > > +}
> > > +
> > > +run libcamera_install_pkgs

This function installs packages that are not
multi-arch compatible. If you disable compilation of apps and gstreamer,
it shouldn't be needed.

> > > +run libcamera_setup
> > > +run libcamera_build_docs collapsed
> > > diff --git a/gitlab-ci.yml b/gitlab-ci.yml
> > > index f887e3b6c221..7c5e59de30a1 100644
> > > --- a/gitlab-ci.yml
> > > +++ b/gitlab-ci.yml
> > > @@ -229,10 +229,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
> > >           CC: clang
> > >           CXX: clang++
> > > @@ -302,6 +298,32 @@ 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:
> > > +      - docs
> > 
> > Could we add
> >    - build/meson-logs/
> >    - build/build.ninja
> > ?
> > 
> > I find these two quite useful in diagnosing build issues, so I think
> > they are worth saving.
> 
> Oh I never looked at these. Sure we can add them.

Sounds like a good idea.

> > > +  variables:
> > > +    # Fixme: Switch to release build as soon as the build issues are fixed.

https://patchwork.libcamera.org/project/libcamera/list/?series=5939

> > > +    BUILD_TYPE: debug
> > > +    MESON_OPTIONS: >-
> > > +      ${MESON_ALL_OPTIONS}
> > > +      -D documentation=enabled
> > > +      -D doc_werror=true

Let's disable everything we don't need.

    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..cccb5bad9cb5
--- /dev/null
+++ b/.gitlab-ci/build-libcamera-docs.sh
@@ -0,0 +1,35 @@ 
+#!/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"
+
+	# Fixme: This should only build the documentation, but as we can't use
+	# the doc tag for installation we need to build everything.
+	meson compile -C build -j$BUILD_CONCURRENT_JOBS
+
+	echo "Installing docs"
+	rm -rf install
+	mkdir install
+
+	# Fixme: This should use --tags doc,doc-internal, but the installation
+	# mechanics are broken and need to be fixed in libcamera. Install the
+	# whole project for now.
+	meson install -C build --destdir $(pwd)/install
+
+	rm -rf docs
+	mv install/usr/local/share/doc/libcamera-*/html docs
+}
+
+run libcamera_install_pkgs
+run libcamera_setup
+run libcamera_build_docs collapsed
diff --git a/gitlab-ci.yml b/gitlab-ci.yml
index f887e3b6c221..7c5e59de30a1 100644
--- a/gitlab-ci.yml
+++ b/gitlab-ci.yml
@@ -229,10 +229,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
         CC: clang
         CXX: clang++
@@ -302,6 +298,32 @@  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:
+      - docs
+  variables:
+    # Fixme: Switch to release build as soon as the build issues are fixed.
+    BUILD_TYPE: debug
+    MESON_OPTIONS: >-
+      ${MESON_ALL_OPTIONS}
+      -D documentation=enabled
+      -D doc_werror=true
+
 # ------------------------------------------------------------------------------
 # Lint stage - Run checkstyle.py and check merge suitability
 # ------------------------------------------------------------------------------