Docs update

.github/actions/build-docs/action.yml

@@ -0,0 +1,29 @@
+name: Build Docs
+description: Install dependencies and build the Docusaurus documentation
+
+runs:
+  using: composite
+  steps:
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.12'
+
+    - name: Set up Node
+      uses: actions/setup-node@v4
+      with:
+        node-version: '20'
+
+    - name: Install dependencies
+      shell: bash
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r docs/python_requirements.txt
+
+    - name: Build docs
+      shell: bash
+      run: |
+        mkdir -p docs/build
+        cd docs/build
+        cmake ../
+        make docusaurus_doc

.github/workflows/build.yml

@@ -43,6 +43,7 @@ jobs:
   deploy:
     needs:
       - build_sdist
+    if: startsWith(github.ref, 'refs/tags/')
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository

.github/workflows/pages.yml

@@ -0,0 +1,27 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [ master ]
+
+jobs:
+
+  build_docs_job:
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Build docs
+        uses: ./.github/actions/build-docs
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/build/docusaurus
+          user_name: github-actions[bot]
+          user_email: 41898282+github-actions[bot]@users.noreply.github.com

.github/workflows/pages_preview.yml

@@ -0,0 +1,86 @@
+name: docs_preview_workflow
+
+# Build the docs for any PR touching docs/ or carrying the 'preview-docs' label
+# and publish them to a per-PR sub-path on gh-pages, e.g.
+# https://hep-soc.github.io/PeakRDL-halcpp/pr-preview/pr-123/
+# The preview is removed automatically when the PR is closed.
+#
+# Note: GITHUB_TOKEN is read-only for pull_request events coming from forks,
+# so this only deploys previews for branches pushed within this repository.
+on:
+  pull_request:
+    types: [opened, reopened, synchronize, closed, labeled]
+
+concurrency:
+  group: docs-preview-${{ github.event.number }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    outputs:
+      run: ${{ steps.gate.outputs.run }}
+    steps:
+      - uses: actions/checkout@v3
+
+      # Only check for file changes on push-like events, not on label or close
+      - uses: dorny/paths-filter@v3
+        id: filter
+        if: github.event.action != 'closed' && github.event.action != 'labeled'
+        with:
+          filters: |
+            docs:
+              - 'docs/**'
+              - '.github/workflows/pages_preview.yml'
+              - '.github/actions/build-docs/**'
+
+      - id: gate
+        shell: bash
+        run: |
+          ACTION="${{ github.event.action }}"
+          HAS_LABEL="${{ contains(github.event.pull_request.labels.*.name, 'preview-docs') }}"
+          DOCS_CHANGED="${{ steps.filter.outputs.docs }}"
+
+          if [[ "$ACTION" == "closed" ]]; then
+            echo "run=true" >> "$GITHUB_OUTPUT"
+          elif [[ "$ACTION" == "labeled" ]]; then
+            # Only rebuild when 'preview-docs' itself is added, not unrelated labels
+            [[ "${{ github.event.label.name }}" == "preview-docs" ]] && \
+              echo "run=true" >> "$GITHUB_OUTPUT" || echo "run=false" >> "$GITHUB_OUTPUT"
+          elif [[ "$HAS_LABEL" == "true" || "$DOCS_CHANGED" == "true" ]]; then
+            echo "run=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "run=false" >> "$GITHUB_OUTPUT"
+          fi
+
+  preview_docs_job:
+    needs: check
+    if: needs.check.outputs.run == 'true'
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+      DOCS_BASE_URL: /PeakRDL-halcpp/pr-preview/pr-${{ github.event.number }}/
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Build docs
+        if: github.event.action != 'closed'
+        uses: ./.github/actions/build-docs
+
+      - name: Deploy / clean up PR preview
+        id: preview
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: ./docs/build/docusaurus
+
+      - name: Print preview URL
+        if: github.event.action != 'closed'
+        run: |
+          echo "Preview URL: ${{ steps.preview.outputs.preview-url }}"
+          echo "### 📖 Docs preview: ${{ steps.preview.outputs.preview-url }}" >> "$GITHUB_STEP_SUMMARY"

docs/.gitignore

@@ -18,3 +18,5 @@
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+
+/static/api_sphinx