doc: Add doc workflow for new doc platform

.github/workflows/doc-build.yml

@@ -0,0 +1,140 @@
+name: Documentation Build
+
+permissions:
+  contents: read
+
+on:
+  workflow_dispatch:
+    inputs:
+      documentation_tag:
+        type: string
+        required: false
+        default: "latest"
+        description: "Label of the documentation"
+      publish_to_prod:
+        type: boolean
+        default: true
+      publish_to_dev:
+        type: boolean
+        default: true
+  pull_request:
+    types: [opened, synchronize, reopened]
+    branches:
+      - main
+      - 'v*-branch'
+    paths:
+      - '.github/workflows/doc-build.yml'
+      - '.github/workflows/doc-publish.yml'
+      - '**.rst'
+      - 'doc/**'
+      - "include/**"
+  push:
+    branches:
+      - main
+      - 'v*-branch'
+    tags:
+      - v*
+
+env:
+  DOXYGEN_VERSION: 1.12.0
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - name: Install system dependencies
+        run: |
+          wget --no-verbose "https://github.com/doxygen/doxygen/releases/download/Release_${DOXYGEN_VERSION//./_}/doxygen-${DOXYGEN_VERSION}.linux.bin.tar.gz"
+          sudo tar xf doxygen-${DOXYGEN_VERSION}.linux.bin.tar.gz -C /opt
+          echo "/opt/doxygen-${DOXYGEN_VERSION}/bin" >> $GITHUB_PATH
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: 3.12
+          cache: pip
+          cache-dependency-path: doc/requirements.txt
+          pip-install: |
+            -r doc/requirements.txt
+
+      - name: Build
+        working-directory: doc
+        run: |
+          doxygen
+          sphinx-build -M html . build
+
+      - name: Check version
+        run: |
+          VERSION_REGEX="^v([0-9a-zA-Z\.\-]+)$"
+          if [[ ${GITHUB_REF#refs/tags/} =~ $VERSION_REGEX ]]; then
+            VERSION=${BASH_REMATCH[1]}
+          elif [[ ${GITHUB_REF#refs/heads/} == "main" ]]; then
+            VERSION="latest"
+          elif [[ "${{ github.event_name }}" == "pull_request" ]]; then
+            VERSION="pr-${{ github.event.number }}"
+          fi
+          echo "VERSION=${VERSION}"
+          echo "VERSION=${VERSION}" >> "$GITHUB_ENV"
+
+      - name: Prepare Azure upload
+        run: |
+          PUBLISH="$PWD/publish"
+          mkdir -p "$PUBLISH"
+
+          MONITOR="monitor_${{ github.run_id }}.txt"
+
+          # Create documentation upload files
+          if [[ "${{ github.event_name }}" == "pull_request" ]]; then
+            ARCHIVE="legacy-addon-serial_modem-pr-${{ github.event.number }}.zip"
+            echo "publish2 dev PR-${{ github.event.number }} ${ARCHIVE}" > "${MONITOR}"
+            echo "${{ github.event.number }}" > pr.txt
+          else
+            ARCHIVE="legacy-addon-serial_modem-${VERSION}.zip"
+            echo "publish2 main ${VERSION} ${ARCHIVE}" > "${MONITOR}"
+          fi
+
+          pushd "doc/build/html"
+          zip -rq "${ARCHIVE}" .
+          mv "${ARCHIVE}" "$PUBLISH"
+          popd
+
+          mv "${MONITOR}" "$PUBLISH"
+          if [[ -f pr.txt ]]; then mv pr.txt "$PUBLISH"; fi
+
+      - name: Prepare Zoomin upload
+        if: ${{ github.event_name == 'push' }}
+        run: |
+          PUBLISH="$PWD/publish"
+          mkdir -p "$PUBLISH"
+
+          OUTDIR=doc/build/html
+          ARCHIVE="addon-serial_modem_$VERSION.zip"
+
+          cp doc/custom.properties "$OUTDIR/custom.properties"
+          sed -i 's/__VERSION__/'"$VERSION"'/g' "$OUTDIR/custom.properties"
+
+          cp doc/tags.yml "$OUTDIR/tags.yml"
+          sed -i 's/__VERSION__/'"$VERSION"'/g' "$OUTDIR/tags.yml"
+
+          pushd "$OUTDIR"
+          zip -rq "$ARCHIVE" .
+          mv "$ARCHIVE" "$PUBLISH"
+          popd
+
+      - name: Store
+        if: ${{ !contains(github.event.pull_request.labels.*.name, 'external') || contains(github.event.pull_request.labels.*.name, 'CI-trusted-author') }}
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        with:
+          name: docs
+          retention-days: 5
+          path: |
+            publish/*

.github/workflows/doc-publish.yml

@@ -0,0 +1,99 @@
+name: Documentation Publish
+
+permissions:
+  contents: read
+  pull-requests: write
+
+on:
+
+  workflow_run:
+    workflows: ["Documentation Build"]
+    types:
+      - completed
+
+jobs:
+  publish:
+    runs-on: ubuntu-24.04
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    steps:
+      - name: Download artifacts
+        uses: dawidd6/action-download-artifact@bf251b5aa9c2f7eeb574a96ee720e24f801b7c11 # v6
+        with:
+          workflow: doc-build.yml
+          run_id: ${{ github.event.workflow_run.id }}
+
+      - name: Unzip html archive
+        working-directory: docs
+        run: |
+          OUTDIR=$(awk 'NR==1 { if ($3 ~ /^(latest|PR-[0-9]+|[0-9]+\.[0-9a-zA-Z\.\-]+)$/) print $3 }' monitor_*.txt)
+          echo "OUTDIR=$OUTDIR" >> "$GITHUB_ENV"
+          unzip legacy-addon-serial_modem*.zip -d $OUTDIR
+          find "$OUTDIR" -type l -delete
+
+      - name: Obtain PR number
+        if: ${{ github.event.workflow_run.event == 'pull_request' }}
+        working-directory: docs
+        run: |
+          if [ -f pr.txt ]; then
+            PR=$(head -n 1 pr.txt | tr -cd '0-9')
+          fi
+          printf 'PR=%s\n' "$PR" >> "$GITHUB_ENV"
+
+      - name: Upload Zoomin documentation
+        if: >
+          github.event.workflow_run.head_branch == 'main' &&
+          github.event.workflow_run.head_repository.full_name == github.repository
+        env:
+          NCS_ZOOMIN_KEY: ${{ secrets.NCS_ZOOMIN_KEY }}
+        run: |
+          # trust server
+          mkdir -p ~/.ssh
+          ssh-keyscan ${{ vars.NCS_ZOOMIN_SERVER }} >> ~/.ssh/known_hosts
+
+          # prepare key
+          touch zoomin_key
+          chmod 600 zoomin_key
+          echo "$NCS_ZOOMIN_KEY" | base64 -d > zoomin_key
+
+          # upload files
+          for file in docs/addon-serial_modem*.zip; do
+            sftp -v -i zoomin_key ${{ vars.NCS_ZOOMIN_USER }}@${{ vars.NCS_ZOOMIN_SERVER }} <<EOF
+              cd docs-be.nordicsemi.com/sphinx-html/incoming
+              put ${file}
+              cd ../../../nordic-be-dev.zoominsoftware.io/sphinx-html/incoming
+              put ${file}
+              quit
+          EOF
+          done
+
+      - name: Upload to Azure storage
+        working-directory: docs
+        env:
+          AZCOPY_CONCURRENCY_VALUE: 1024
+          NCS_DOC_SAS_PRS: ${{ secrets.NCS_DOC_SAS_PRS }}
+          NCS_DOC_SAS_MAIN: ${{ secrets.NCS_DOC_SAS_MAIN }}
+        run: |
+          if [[ "${{ github.event.workflow_run.event }}" == "pull_request" ]]; then
+            azcopy cp $OUTDIR "${{ vars.NCS_DOC_PR_STORAGE_URL }}addon-serial_modem?$NCS_DOC_SAS_PRS" --recursive=true
+          else
+            azcopy cp $OUTDIR "${{ vars.NCS_DOC_STORAGE_URL }}addon-serial_modem?$NCS_DOC_SAS_MAIN" --recursive=true
+          fi
+
+      - name: Find Comment
+        if: ${{ github.event.workflow_run.event == 'pull_request' }}
+        uses: peter-evans/find-comment@3eae4d37986fb5a8592848f6a574fdf654e61f9e # v3
+        id: fc
+        with:
+          issue-number: ${{ env.PR }}
+          comment-author: 'github-actions[bot]'
+          body-includes: documentation preview
+
+      - name: Create or update comment
+        if: ${{ github.event.workflow_run.event == 'pull_request' }}
+        uses: peter-evans/create-or-update-comment@71345be0265236311c031f5c7866368bd1eff043 # v4
+        with:
+          comment-id: ${{ steps.fc.outputs.comment-id }}
+          issue-number: ${{ env.PR }}
+          body: |
+            You can find the documentation preview for this PR [here](${{ vars.NCS_DOC_PR_HOSTING_URL }}addon-serial_modem/PR-${{ env.PR }}/).
+          edit-mode: replace

.github/workflows/doc-remove.yml

@@ -0,0 +1,20 @@
+name: Documentation Remove
+
+permissions:
+  contents: read
+
+on:
+  pull_request_target:
+    types: [closed]
+    branches:
+      - main
+
+jobs:
+  remove:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Try removal of PR-docs
+        env:
+          AZCOPY_CONCURRENCY_VALUE: 3000
+        run: |
+          azcopy rm "${{ vars.NCS_DOC_PR_STORAGE_URL }}addon-serial_modem/PR-${{ github.event.number }}?${{ secrets.NCS_DOC_SAS_PRS }}" --recursive=true || true

doc/conf.py

@@ -36,6 +36,11 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = 'sphinx_ncs_theme'
+html_theme_options = {
+    'docsets': {},
+}
+
+html_extra_path = ['versions.json']
 
 ## -- Options for Breathe ----------------------------------------------------
 # https://breathe.readthedocs.io/en/latest/index.html

doc/requirements.txt

@@ -1,6 +1,6 @@
 Sphinx==5.3.0
 breathe==4.35.0
-sphinx-ncs-theme==0.7.4
+sphinx-ncs-theme<1.1
 sphinx-tabs>=3.4
 sphinx-togglebutton>=0.3.2
 Pillow>=9.0.1