From ce47303e3540907e7aa4eaab5a63522f116e5e3d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pablo=20Correa=20G=C3=B3mez?=
 <pabloyoyoista@postmarketos.org>
Date: Tue, 23 Sep 2025 09:47:09 +0200
Subject: [PATCH] ci: add job to build docs and trigger handbook pipeline for
 deployment

Part-of: https://gitlab.postmarketos.org/postmarketOS/pmaports/-/merge_requests/7065

[ci:skip-build]: already built successfully in CI
---
 .ci/build-docs.sh | 22 ++++++++++++++++++++++
 .gitlab-ci.yml    | 22 ++++++++++++++++++++++
 2 files changed, 44 insertions(+)
 create mode 100755 .ci/build-docs.sh

diff --git a/.ci/build-docs.sh b/.ci/build-docs.sh
new file mode 100755
index 000000000..29c754a57
--- /dev/null
+++ b/.ci/build-docs.sh
@@ -0,0 +1,22 @@
+#!/bin/sh -e
+# Copyright 2025 Pablo Correa Gomez
+# SPDX-License-Identifier: GPL-3.0-or-later
+# Description: create documentation with sphinx
+# Options: with-dot-git
+# Artifacts: build/site
+# https://postmarketos.org/pmb-ci
+
+
+# Install dependencies
+if [ "$(id -u)" = 0 ]; then
+	set -x
+	apk -q add git nodejs npm
+	exec su "${TESTUSER:-build}" -c "sh -e $0"
+fi
+
+npm install antora
+npx antora -v
+
+# FIXME: https://gitlab.com/antora/antora/-/issues/1183
+git clone --depth 1 https://gitlab.postmarketos.org/postmarketOS/handbook
+npx antora --clean antora-test.yml
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 738b35701..2157e6389 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -10,6 +10,7 @@ stages:
   - build
   - autoupdate
   - test
+  - deploy
 variables:
   # Default of 20 is pretty small, sometimes MRs have >20 commits in them. 100
   # seems like a reasonable balance. If this is too low, git merge-base (from ci/
@@ -193,6 +194,27 @@ build-jobs:
   rules:
     - if: *mr_rule
 
+build-docs:
+  stage: build
+  before_script:
+    - adduser -D build
+  script:
+    - .ci/build-docs.sh
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+      changes:
+        - docs/**/*
+
+deploy-docs:
+  stage: deploy
+  trigger:
+    project: postmarketOS/handbook
+    strategy: depend
+  rules:
+    - if: $CI_COMMIT_BRANCH == "master" && $CI_PROJECT_NAMESPACE == "postmarketOS"
+      changes:
+        - docs/**/*
+
 auto-update:
   stage: autoupdate
   rules: