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

@@ -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

.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: