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

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

Commit Message

Stefan Klug May 6, 2026, 3:54 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>
---
 .gitlab-ci/build-libcamera-docs.sh | 28 ++++++++++++++++++++++++++++
 gitlab-ci.yml                      | 29 +++++++++++++++++++++++++----
 2 files changed, 53 insertions(+), 4 deletions(-)
 create mode 100755 .gitlab-ci/build-libcamera-docs.sh

Comments

Laurent Pinchart May 6, 2026, 6:03 p.m. UTC | #1 
Hi Stefan,

Thank you for the patch.

On Wed, May 06, 2026 at 05:54:11PM +0200, Stefan Klug wrote:
> 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>
> ---
>  .gitlab-ci/build-libcamera-docs.sh | 28 ++++++++++++++++++++++++++++
>  gitlab-ci.yml                      | 29 +++++++++++++++++++++++++----
>  2 files changed, 53 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..a2ee7ba839d8
> --- /dev/null
> +++ b/.gitlab-ci/build-libcamera-docs.sh
> @@ -0,0 +1,28 @@
> +#!/bin/bash
> +
> +# SPDX-License-Identifier: GPL-2.0-or-later
> +# SPDX-FileCopyrightText: © 2023 Laurent Pinchart <laurent.pinchart@ideasonboard.com>

You can update this.

> +#
> +# Build libcamera

Note quite right :-)

> +
> +set -e
> +
> +source "$(dirname "$0")/lib.sh"
> +source "$(dirname "$0")/build-libcamera-common.sh"
> +
> +libcamera_build_docs() {
> +	echo "Building libcamera"

Same here.

> +
> +	meson compile -C build -j$BUILD_CONCURRENT_JOBS documentation
> +	(

Why do you create a subshell here ?

> +		cd build
> +		rm -rf docs
> +		mv Documentation/html/ docs
> +		rm -rf docs/{internal,public}-api
> +		mv Documentation/{internal,public}-api docs/

Could you install the documentation, and copy/move directories from the
installation directory instead of the build directory ? That will help
testing the documentation installation process. You can use the meson
install --tags options to install the documentation only and skip
compilation of the rest of libcamera.

> +	)
> +}
> +
> +run libcamera_install_pkgs

I think you can skip this if you only build the documentation.

> +run libcamera_setup
> +run libcamera_build_docs collapsed
> diff --git a/gitlab-ci.yml b/gitlab-ci.yml
> index f887e3b6c221..468f5769eb87 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,31 @@ 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/docs
> +  variables:
> +    BUILD_TYPE: release
> +    MESON_OPTIONS: >-
> +      ${MESON_ALL_OPTIONS}
> +      -D documentation=enabled
> +      -D doc_werror=true
> +
>  # ------------------------------------------------------------------------------
>  # Lint stage - Run checkstyle.py and check merge suitability
>  # ------------------------------------------------------------------------------
Stefan Klug May 7, 2026, 7:06 a.m. UTC | #2 
Hi Laurent,

Thank you for the review.

Quoting Laurent Pinchart (2026-05-06 20:03:53)
> Hi Stefan,
> 
> Thank you for the patch.
> 
> On Wed, May 06, 2026 at 05:54:11PM +0200, Stefan Klug wrote:
> > 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>
> > ---
> >  .gitlab-ci/build-libcamera-docs.sh | 28 ++++++++++++++++++++++++++++
> >  gitlab-ci.yml                      | 29 +++++++++++++++++++++++++----
> >  2 files changed, 53 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..a2ee7ba839d8
> > --- /dev/null
> > +++ b/.gitlab-ci/build-libcamera-docs.sh
> > @@ -0,0 +1,28 @@
> > +#!/bin/bash
> > +
> > +# SPDX-License-Identifier: GPL-2.0-or-later
> > +# SPDX-FileCopyrightText: © 2023 Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> 
> You can update this.

Yes, sure. Should we change that to a generic Ideas on Board?
> 
> > +#
> > +# Build libcamera
> 
> Note quite right :-)
> 
> > +
> > +set -e
> > +
> > +source "$(dirname "$0")/lib.sh"
> > +source "$(dirname "$0")/build-libcamera-common.sh"
> > +
> > +libcamera_build_docs() {
> > +     echo "Building libcamera"
> 
> Same here.
> 
> > +
> > +     meson compile -C build -j$BUILD_CONCURRENT_JOBS documentation
> > +     (
> 
> Why do you create a subshell here ?

I don't want the working dir to be modified by the call to the function.
A pushd/popd combination would work as well but has a tendency to fail
if you add early return paths. So I guess the subshell grew into a habit.
Do you have any particular preferences?

> 
> > +             cd build
> > +             rm -rf docs
> > +             mv Documentation/html/ docs
> > +             rm -rf docs/{internal,public}-api
> > +             mv Documentation/{internal,public}-api docs/
> 
> Could you install the documentation, and copy/move directories from the
> installation directory instead of the build directory ? That will help
> testing the documentation installation process. You can use the meson
> install --tags options to install the documentation only and skip
> compilation of the rest of libcamera.

Yes, that is reasonable.

I'll fix these things.

Best regards,
Stefan

> 
> > +     )
> > +}
> > +
> > +run libcamera_install_pkgs
> 
> I think you can skip this if you only build the documentation.
> 
> > +run libcamera_setup
> > +run libcamera_build_docs collapsed
> > diff --git a/gitlab-ci.yml b/gitlab-ci.yml
> > index f887e3b6c221..468f5769eb87 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,31 @@ 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/docs
> > +  variables:
> > +    BUILD_TYPE: release
> > +    MESON_OPTIONS: >-
> > +      ${MESON_ALL_OPTIONS}
> > +      -D documentation=enabled
> > +      -D doc_werror=true
> > +
> >  # ------------------------------------------------------------------------------
> >  # Lint stage - Run checkstyle.py and check merge suitability
> >  # ------------------------------------------------------------------------------
> 
> -- 
> Regards,
> 
> Laurent Pinchart
Laurent Pinchart May 7, 2026, 8:25 a.m. UTC | #3 
On Thu, May 07, 2026 at 09:06:24AM +0200, Stefan Klug wrote:
> Quoting Laurent Pinchart (2026-05-06 20:03:53)
> > On Wed, May 06, 2026 at 05:54:11PM +0200, Stefan Klug wrote:
> > > 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>
> > > ---
> > >  .gitlab-ci/build-libcamera-docs.sh | 28 ++++++++++++++++++++++++++++
> > >  gitlab-ci.yml                      | 29 +++++++++++++++++++++++++----
> > >  2 files changed, 53 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..a2ee7ba839d8
> > > --- /dev/null
> > > +++ b/.gitlab-ci/build-libcamera-docs.sh
> > > @@ -0,0 +1,28 @@
> > > +#!/bin/bash
> > > +
> > > +# SPDX-License-Identifier: GPL-2.0-or-later
> > > +# SPDX-FileCopyrightText: © 2023 Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> > 
> > You can update this.
> 
> Yes, sure. Should we change that to a generic Ideas on Board?

Works fine for me.

> > > +#
> > > +# Build libcamera
> > 
> > Note quite right :-)
> > 
> > > +
> > > +set -e
> > > +
> > > +source "$(dirname "$0")/lib.sh"
> > > +source "$(dirname "$0")/build-libcamera-common.sh"
> > > +
> > > +libcamera_build_docs() {
> > > +     echo "Building libcamera"
> > 
> > Same here.
> > 
> > > +
> > > +     meson compile -C build -j$BUILD_CONCURRENT_JOBS documentation
> > > +     (
> > 
> > Why do you create a subshell here ?
> 
> I don't want the working dir to be modified by the call to the function.
> A pushd/popd combination would work as well but has a tendency to fail
> if you add early return paths. So I guess the subshell grew into a habit.
> Do you have any particular preferences?

Makes sense. Let's see if changing directory will still be needed after
the change described below.

> > > +             cd build
> > > +             rm -rf docs
> > > +             mv Documentation/html/ docs
> > > +             rm -rf docs/{internal,public}-api
> > > +             mv Documentation/{internal,public}-api docs/
> > 
> > Could you install the documentation, and copy/move directories from the
> > installation directory instead of the build directory ? That will help
> > testing the documentation installation process. You can use the meson
> > install --tags options to install the documentation only and skip
> > compilation of the rest of libcamera.
> 
> Yes, that is reasonable.
> 
> I'll fix these things.
> 
> Best regards,
> Stefan
> 
> > > +     )
> > > +}
> > > +
> > > +run libcamera_install_pkgs
> > 
> > I think you can skip this if you only build the documentation.
> > 
> > > +run libcamera_setup
> > > +run libcamera_build_docs collapsed
> > > diff --git a/gitlab-ci.yml b/gitlab-ci.yml
> > > index f887e3b6c221..468f5769eb87 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,31 @@ 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/docs
> > > +  variables:
> > > +    BUILD_TYPE: release
> > > +    MESON_OPTIONS: >-
> > > +      ${MESON_ALL_OPTIONS}
> > > +      -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..a2ee7ba839d8
--- /dev/null
+++ b/.gitlab-ci/build-libcamera-docs.sh
@@ -0,0 +1,28 @@ 
+#!/bin/bash
+
+# SPDX-License-Identifier: GPL-2.0-or-later
+# SPDX-FileCopyrightText: © 2023 Laurent Pinchart <laurent.pinchart@ideasonboard.com>
+#
+# Build libcamera
+
+set -e
+
+source "$(dirname "$0")/lib.sh"
+source "$(dirname "$0")/build-libcamera-common.sh"
+
+libcamera_build_docs() {
+	echo "Building libcamera"
+
+	meson compile -C build -j$BUILD_CONCURRENT_JOBS documentation
+	(
+		cd build
+		rm -rf docs
+		mv Documentation/html/ docs
+		rm -rf docs/{internal,public}-api
+		mv Documentation/{internal,public}-api 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..468f5769eb87 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,31 @@  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/docs
+  variables:
+    BUILD_TYPE: release
+    MESON_OPTIONS: >-
+      ${MESON_ALL_OPTIONS}
+      -D documentation=enabled
+      -D doc_werror=true
+
 # ------------------------------------------------------------------------------
 # Lint stage - Run checkstyle.py and check merge suitability
 # ------------------------------------------------------------------------------