build docs preview and production builds in GitHub CI

.github/workflows/documentation.yml

@@ -4,8 +4,10 @@ on:
   push:
     branches:
     - 'main'
+    - 'documentation'
     tags:
     - '**'
+    pull_request:
 
 concurrency:
   # group workflow runs based on the branch or the tag ref
@@ -16,19 +18,23 @@ concurrency:
 # - GH_DOCS_WRITE_KEY: generated locally, added to github repo (public key)
 #                    `ssh-keygen -t rsa -b 4096 -C "Github CI Docs Key" -N "" -f key`
 # - GITHUB_TOKEN: (default, from github actions)
+# - NETLIFY_AUTH_TOKEN: an access token to use when authenticating commands on Netlify
+# - NETLIFY_SITE_ID: the API ID of the Netlify site for the docs
 
 env:
   DOCS_FOLDER: docs
   DOCS_BRANCH: documentation
   TAG_NAME: ${GITHUB_REF#refs/tags/}
   IS_TAG_BUILD: ${{ startsWith(github.event.ref, 'refs/tags') }}
   IS_MAIN_BRANCH: ${{ github.ref == 'refs/heads/main' }}
+  IS_PULL_REQUEST: ${{ github.head_ref != 0 }}
 
 jobs:
   evaluate_release_tag:
     name: Evaluate release tag
     runs-on: ubuntu-latest
-    if: github.repository == 'RasaHQ/rasa'  # don't run this for main branches of forks, would fail anyways
+    # don't run this for main branches of forks and on documentation branch
+    if: github.repository == 'RasaHQ/rasa' && github.ref != 'refs/heads/documentation' && env.IS_PULL_REQUEST == 'false'
     outputs:
       build_docs: ${{ steps.check_tag.outputs.build_docs }}
 
@@ -94,11 +100,12 @@ jobs:
 
         echo "::set-output name=build_docs::false"
 
-  docs:
-    name: Build Docs
+  prebuild_docs:
+    name: Prebuild Docs
     runs-on: ubuntu-latest
     needs: [ evaluate_release_tag ]
-    if: github.repository == 'RasaHQ/rasa' && needs.evaluate_release_tag.outputs.build_docs == 'true'  # don't run this for main branches of forks, would fail anyways
+    # don't run this for main branches of forks, would fail anyways
+    if: github.repository == 'RasaHQ/rasa' && needs.evaluate_release_tag.outputs.build_docs == 'true' && github.ref != 'refs/heads/documentation' && env.IS_PULL_REQUEST == 'false'
 
     steps:
     - name: Checkout git repository 🕝
@@ -144,7 +151,7 @@ jobs:
     - name: Pre-build Docs 🧶
       run: make prepare-docs
 
-    - name: Build & Publish Docs 🏃‍♀️
+    - name: Push docs to documentation branch 🏃‍♀️
       env:
         GH_DOCS_WRITE_KEY: ${{ secrets.GH_DOCS_WRITE_KEY }}
         TMP_DOCS_FOLDER: /tmp/documentation-${{ github.run_id }}
@@ -169,3 +176,103 @@ jobs:
         channel_id: ${{ secrets.SLACK_ALERTS_CHANNEL_ID }}
         status: FAILED
         color: warning
+
+
+  preview_docs:
+    name: Preview Docs
+    runs-on: ubuntu-latest
+    # don't run this for main branches of forks; only run on pull requests
+    if: github.repository == 'RasaHQ/rasa' && env.IS_PULL_REQUEST == 'true'
+
+    steps:
+    - name: Checkout git repository 🕝
+      uses: actions/checkout@v2
+
+    - name: Set up Python 3.7 🐍
+      uses: actions/setup-python@dc73133d4da04e56a135ae2246682783cc7c7cb6  # v2.2.2
+      with:
+        python-version: 3.7
+
+    - name: Set up Node 12.x 🦙
+      uses: actions/[email protected]
+      with:
+        node-version: '12.x'
+
+    - name: Read Poetry Version 🔢
+      run: |
+        echo "POETRY_VERSION=$(scripts/poetry-version.sh)" >> $GITHUB_ENV
+      shell: bash
+
+    - name: Install poetry 🦄
+      uses: Gr1N/setup-poetry@v7
+      with:
+        poetry-version: ${{ env.POETRY_VERSION }}
+
+    - name: Load Poetry Cached Libraries ⬇
+      uses: actions/cache@v1
+      with:
+        path: ~/.cache/pypoetry/virtualenvs
+        key: ${{ runner.os }}-poetry-${{ env.POETRY_VERSION }}-3.7-non-full-${{ hashFiles('**/poetry.lock') }}-${{ secrets.POETRY_CACHE_VERSION }}
+        restore-keys: ${{ runner.os }}-poetry-3.7-non-full
+
+    - name: Load Yarn Cached Packages ⬇
+      uses: actions/cache@v1
+      with:
+        path: docs/node_modules
+        key: ${{ runner.os }}-yarn-12.x-${{ hashFiles('docs/yarn.lock') }}
+        restore-keys: ${{ runner.os }}-yarn-12.x
+
+    - name: Install Dependencies 📦
+      run: make install install-docs
+
+    - name: Pre-build Docs 🧶
+      run: make prepare-docs
+
+    - name: Preview draft build 🔬
+      env:
+        NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+        NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
+        BRANCH: ${{ env.GITHUB_REF_NAME }}
+      run: make preview-docs
+
+
+  publish_docs:
+    name: Publish Docs
+    runs-on: ubuntu-latest
+    # don't run this for main branches of forks; only run on documentation branch
+    if: github.repository == 'RasaHQ/rasa' && github.ref == 'refs/heads/documentation'
+
+    steps:
+    - name: Checkout git repository 🕝
+      uses: actions/checkout@v2
+
+    - name: Set up Node 12.x 🦙
+      uses: actions/[email protected]
+      with:
+        node-version: '12.x'
+
+    - name: Load Yarn Cached Packages ⬇
+      uses: actions/cache@v1
+      with:
+        path: docs/node_modules
+        key: ${{ runner.os }}-yarn-12.x-${{ hashFiles('docs/yarn.lock') }}
+        restore-keys: ${{ runner.os }}-yarn-12.x
+
+    - name: Install Dependencies 📦
+      run: make install-docs
+
+    - name: Publish production build ✅
+      env:
+        NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+        NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
+      run: make publish-docs
+
+    - name: Notify slack on failure
+      if: failure()
+      env:
+        SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
+      uses: voxmedia/github-action-slack-notify-build@212e9f7a9ca33368c8dd879d6053972128258985  # v1.5.0
+      with:
+        channel_id: ${{ secrets.SLACK_ALERTS_CHANNEL_ID }}
+        status: FAILED
+        color: warning

Makefile

@@ -232,6 +232,13 @@ docs: prepare-docs
 livedocs:
 	cd docs/ && poetry run yarn start
 
+BRANCH ?= main
+preview-docs:
+	cd docs/ && yarn build && yarn deploy-preview --alias=$(BRANCH)
+
+publish-docs:
+	cd docs/ && yarn build && yarn deploy
+
 release:
 	poetry run python scripts/release.py
 

docs/package.json

@@ -11,7 +11,8 @@
     "develop": "docusaurus start --port 3000",
     "build": "docusaurus build --out-dir build/docs/rasa",
     "serve": "netlify dev --dir=build --port=5000",
-    "deploy": "netlify deploy --dir=build --alias=staging --open",
+    "deploy-preview": "netlify deploy --dir=build",
+    "deploy": "netlify deploy --dir=build --prod",
     "new-version": "docusaurus docs:version",
     "variables": "node scripts/compile_variables.js",
     "program-outputs": "node scripts/compile_program_outputs.js",