refactor: v3 (GH-158, GH-61) mkdocs-tacc theme, netlify deploys (#246)

## Overview

- Support TACC theme properly.
- Support live preview server for each PR.
- Set version to `3.0.0`.

## Changes

- #240
  - #241
- #243
  - #244
- #245

Author: wesleyboar

.github/CODEOWNERS

@@ -3,26 +3,24 @@
 # architecture
 /*                 @wesleyboar
 /.github/          @wesleyboar
-/user-guide/themes @wesleyboar
 
 # settings
-/user-guide/docs/index.md @wesleyboar
-/user-guide/mkdocs.yml    @wesleyboar
+/user-guide/index.md @wesleyboar
+
+# assets
+*.js  @wesleyboar
+js/   @wesleyboar
+*.css @wesleyboar
+css/  @wesleyboar
 
 # OpenSees
-/user-guide/docs/tools/simulation/opensees.md  @silviamazzoni
-/user-guide/docs/tools/simulation/opensees/    @silviamazzoni
-/user-guide/docs/tools/simulation/openseesOld/ @silviamazzoni
+/user-guide/tools/simulation/opensees.md  @silviamazzoni
+/user-guide/tools/simulation/opensees/    @silviamazzoni
+/user-guide/tools/simulation/openseesOld/ @silviamazzoni
 
 # ADCIRC
-# /user-guide/docs/tools/simulation/adcirc.md @cdelcastillo21
-# /user-guide/docs/tools/simulation/adcirc/   @cdelcastillo21
+# /user-guide/tools/simulation/adcirc.md @cdelcastillo21
+# /user-guide/tools/simulation/adcirc/   @cdelcastillo21
 
 # Arduino
-# /user-guide/docs/usecases/arduino/ @parduino
-
-# static assets
-*.js  @wesleyboar
-js/   @wesleyboar
-*.css @wesleyboar
-css/  @wesleyboar
+# /user-guide/usecases/arduino/ @parduino

.github/workflows/build-pprd.yml

@@ -1,4 +1,4 @@
-name: DS User Guide Builds
+name: Build and Push
 
 on:
   workflow_dispatch:
@@ -11,19 +11,23 @@ on:
   push:
     branches:
       - main
+      - pprd
+      - epic/v3
+      - epic/v3--*
+      - any/branch-you-want
 
 jobs:
   docker:
     runs-on: ubuntu-latest
     steps:
-      -
-        name: Set up Docker Buildx
+
+      - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v2
-      -
-        name: Checkout repo
+
+      - name: Checkout repo
         uses: actions/checkout@v3
-      -
-        name: Get shortsha and branch name
+
+      - name: Get shortsha and branch name
         id: vars
         run: |
           if [ -z "$EVENT_SHA" ]; then SHORT_SHA=${GITHUB_SHA::8}; else SHORT_SHA=${EVENT_SHA::8}; fi
@@ -32,27 +36,44 @@ jobs:
           echo ::set-output name=ref_short::${SHORT_REF}
         env:
           EVENT_SHA: ${{ github.event.client_payload.sha }}
+
+      - name: Determine environment tag
+        id: env_tag
+        run: |
+          if [ -n "${{ inputs.tag_custom }}" ]; then
+            ENV_TAG="${{ inputs.tag_custom }}"
+          elif [ "${{ github.ref_name }}" = "main" ]; then
+            ENV_TAG="latest"
+          elif [ "${{ github.ref_name }}" = "pprd" ]; then
+            ENV_TAG="pprd"
+          else
+            ENV_TAG="${{ steps.vars.outputs.ref_short }}"
+          fi
+          echo ::set-output name=env_tag::${ENV_TAG}
+
       - name: Print vars
         run: |
-          echo $SHORT_SHA
-          echo $SHORT_REF
+          echo "Short SHA: $SHORT_SHA"
+          echo "Short Ref: $SHORT_REF"
+          echo "Environment Tag: $ENV_TAG"
         env:
           SHORT_SHA: ${{ steps.vars.outputs.sha_short }}
           SHORT_REF: ${{ steps.vars.outputs.ref_short }}
-      -
-        name: Login to Docker Hub
+          ENV_TAG: ${{ steps.env_tag.outputs.env_tag }}
+
+      - name: Login to Docker Hub
         uses: docker/login-action@v2
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
-      -
-        name: Build and push
+
+      - name: Build and push
         uses: docker/build-push-action@v3
         with:
           push: true
-          tags: designsafeci/ds-user-guide:${{ inputs.tag_custom && inputs.tag_custom || 'latest' }},designsafeci/ds-user-guide:${{ steps.vars.outputs.sha_short }},designsafeci/ds-user-guide:${{ steps.vars.outputs.ref_short }}
-      -
-        name: Post build status in slack
+          tags: designsafeci/ds-user-guide:${{ steps.env_tag.outputs.env_tag }},designsafeci/ds-user-guide:${{ steps.vars.outputs.sha_short }},designsafeci/ds-user-guide:${{ steps.vars.outputs.ref_short }}
+
+      - name: Post build status in slack
         id: slack
         uses: slackapi/[email protected]
         with:

.github/workflows/build-preview.yml

@@ -0,0 +1,45 @@
+# Humans should not manage requirements.txt (bots do)
+name: Validate requirements.txt not changed by human
+
+on:
+  pull_request:
+    paths: ['requirements.txt']
+    types: [opened, synchronize, reopened]
+
+jobs:
+  reject-requirements-drift:
+    # To temporarily ignore epic/v3 branch, which introduces requirements.txt
+    # TODO: Delete this after merging #246
+    if: "!startsWith(github.head_ref, 'epic/')"
+
+    runs-on: ubuntu-latest
+
+    # Skip if the last commit was from the bot (prevent unnecessary check)
+    if: github.event.head_commit.author.name != 'github-actions[bot]'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # full history
+
+      - name: Check if requirements.txt was modified unexpectedly
+        run: |
+          # For PRs, check against base branch
+          # For pushes, check last commit
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            BASE_REF="${{ github.event.pull_request.base.sha }}"
+            COMPARE_RANGE="$BASE_REF...HEAD"
+          else
+            COMPARE_RANGE="HEAD~1..HEAD"
+          fi
+
+          # If requirements.txt modified in that range
+          if git diff --name-only $COMPARE_RANGE | grep -q "^requirements.txt$"; then
+            echo "::error::You may NOT edit 'requirements.txt'"
+            echo "::warning::Undo your changes to requirements.txt, so robot can maintain it."
+            echo "::notice::To pin dependencies, use 'poetry add <package-name>'."
+            exit 1
+          fi
+
+          echo "'requirements.txt' unchanged (or only changed by bot)"

.github/workflows/build.yml

@@ -0,0 +1,85 @@
+# Netlify requires requirements.txt (humans do not)
+name: Sync requirements.txt with pyproject.toml
+
+on:
+  pull_request:
+    paths: ['pyproject.toml']
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: write
+
+jobs:
+  detect-requirements-delta:
+    runs-on: ubuntu-latest
+    outputs:
+      has_change: ${{ steps.detect.outputs.has_change }}
+
+    # Skip if the last commit was from the bot (prevent infinite loops)
+    if: github.event.head_commit.author.name != 'github-actions[bot]'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.head_ref || github.ref_name }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: 'pyproject.toml'
+
+      - name: Install Poetry
+        run: pip install poetry
+
+      - name: Detect whether requirements.txt has change
+        id: detect
+        run: |
+          output=$(make requirements.txt 2>&1)
+          echo "$output"
+
+          # Check whether Make output suggests file is up to date
+          if echo "$output" | grep -qi "up to date\|up-to-date\|already up to date"; then
+            echo "has_change=false" >> $GITHUB_OUTPUT
+            echo "::notice::requirements.txt seems up to date"
+          else
+            echo "has_change=true" >> $GITHUB_OUTPUT
+          fi
+
+  commit-requirements-delta:
+    runs-on: ubuntu-latest
+    needs: detect-requirements-delta
+    if: needs.detect-requirements-delta.outputs.has_change == 'true'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.head_ref || github.ref_name }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: 'pyproject.toml'
+
+      - name: Install Poetry
+        run: pip install poetry
+
+      - name: Generate requirements.txt
+        run: make requirements.txt
+
+      - name: Configure Git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Commit requirements.txt if changed
+        run: |
+          git add -f requirements.txt
+          if git diff --staged --quiet; then
+            echo "No changes to requirements.txt"
+          else
+            git commit -m "chore: auto-update requirements.txt [bot]"
+            git push
+          fi

.github/workflows/requirements-validate.yml

@@ -1,19 +1,14 @@
-# Ignore site
-user-guide/site/
+# build
+site/
 
-# TACC files
-mkdocs.base.yml
-poetry.lock
-pyproject.toml
-user-guide/docs/**/core
-user-guide/themes/tacc-readthedocs
-
-# Temporary files
+# os
 .DS_Store
 
-# Igonre pyenv
+# python
 .python-version
+# python: only for Netlify, which does not support pyproject.toml yet
+requirements.txt
 
-# Ignore user configs
+# ide
 .vs
 .vscode