Merge pull request #287 from stride3d/master

Initiating deployment of latest docs updates to production
stride3d · May 5, 2024 · 20e606d · 20e606d
2 parents 86428f8 + ae35397
commit 20e606d
Show file tree

Hide file tree

Showing 101 changed files with 1,401 additions and 1,331 deletions.
diff --git a/.github/release.yml b/.github/release.yml
@@ -0,0 +1,40 @@
+changelog:
+  exclude:
+    labels:
+      - ignore-for-release
+    authors:
+      - dependabot
+  categories:
+    - title: 💥 Breaking Changes
+      labels:
+        - 'breaking-change'
+    - title: 🎉 New Features
+      labels:
+        - 'new-feature'
+    - title: 🐞 Bug Fixes
+      labels:
+        - 'bug-fix'
+    - title: 🏋🏽 Community Resources
+      labels:
+        - 'community-resources'
+    - title: 🌟 Contributing
+      labels:
+        - 'contributing'
+    - title: 🔧 API
+      labels:
+        - API
+    - title: 📝 Release Notes
+      labels:
+        - 'release-notes'
+    - title: 📚 Manual
+      labels:
+        - manual
+    - title: 🎓 Tutorials
+      labels:
+        - 'tutorial'
+    - title: 🔁 Build & Deploy
+      labels:
+        - 'ci-cd'
+    - title: 💪 Other Changes
+      labels:
+        - "*"
diff --git a/.github/workflows/common-setup.yml b/.github/workflows/common-setup.yml
@@ -0,0 +1,49 @@
+name: Common Setup for Stride Documentation
+
+# This is not used currently. The job runs in a separate instants so can't be used
+on:
+  workflow_call:
+    outputs:
+      stride_docs_path:
+        description: "The checkout path of the Stride Docs repository"
+        value: ${{ jobs.setup.outputs.stride_docs_path }}
+      stride_path:
+        description: "The checkout path of the Stride repository"
+        value: ${{ jobs.setup.outputs.stride_path }}
+
+jobs:
+  setup:
+    runs-on: windows-2022
+
+    outputs:
+      stride-docs-path: 'stride-docs'
+      stride-path: 'stride'
+
+    steps:
+    # Setup .NET SDK
+    - name: Dotnet Setup
+      uses: actions/setup-dotnet@v4
+      with:
+        dotnet-version: 8.x
+
+    # Checkout the Stride Docs repository from the branch that triggered the workflow
+    - name: Checkout Stride Docs
+      uses: actions/checkout@v4
+      with:
+        path: stride-docs
+        lfs: true
+
+    # Checkout the Stride repository from the default branch
+    - name: Checkout Stride (note the LFS)
+      uses: actions/checkout@v4
+      with:
+        repository: stride3d/stride
+        token: ${{ secrets.GITHUB_TOKEN }}
+        path: stride
+        lfs: true
+
+    - name: Install DocFX
+      # This installs the latest version of DocFX and may introduce breaking changes
+      # run: dotnet tool update -g docfx
+      # This installs a specific, tested version of DocFX.
+      run: dotnet tool update -g docfx --version 2.76.0
diff --git a/.github/workflows/stride-docs-github.yml b/.github/workflows/stride-docs-github.yml
@@ -2,6 +2,11 @@
 
 name: Build Stride Docs for GitHub Staging
 
+env:
+  COMMON_SETTINGS_PATH: en/docfx.json
+  VERSION: "2.0.0.${{ github.run_number }}"
+  DOCS_PATH: stride-docs
+
 on:
   workflow_dispatch:
 
@@ -10,35 +15,47 @@ jobs:
     runs-on: windows-2022
 
     steps:
-      - name: Dotnet Setup
-        uses: actions/setup-dotnet@v3
-        with:
-          dotnet-version: 8.x
-
-      - name: Checkout Stride Docs
-        uses: actions/checkout@v3
-        with:
-          path: stride-docs
-          lfs: true
-
-      - name: Checkout Stride (note the LFS)
-        uses: actions/checkout@v3
-        with:
-          repository: stride3d/stride
-          token: ${{ secrets.GITHUB_TOKEN }}
-          path: stride
-          lfs: true
-
-      - name: Install DocFX
-        run: dotnet tool update -g docfx --version 2.74.0
-
-      - name: Build documentation
-        run: ./build-all.bat
-        working-directory: stride-docs
-
-      - name: Deploy
-        uses: peaceiris/actions-gh-pages@v3.9.2
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: stride-docs/_site
-          publish_branch: gh-pages
+    - name: .NET SDK Setup
+      uses: actions/setup-dotnet@v4
+      with:
+        dotnet-version: 8.x
+
+    # Checkout the Stride Docs repository from the branch that triggered the workflow
+    - name: Checkout Stride Docs
+      uses: actions/checkout@v4
+      with:
+        path: ${{ env.DOCS_PATH }}
+        lfs: true
+
+    - name: Set Version in docfx.json
+      run: |
+        $settingsContent = Get-Content -Path "${{ env.DOCS_PATH }}/${{ env.COMMON_SETTINGS_PATH }}" -Raw
+        $updatedDocFxJsonContent = $settingsContent -replace '2.0.0.x', "${{ env.VERSION }}"
+        Set-Content -Path "${{ env.DOCS_PATH }}/${{ env.COMMON_SETTINGS_PATH }}" -Value $updatedDocFxJsonContent
+      shell: pwsh
+
+    # Checkout the Stride repository from the default branch
+    - name: Checkout Stride (note the LFS)
+      uses: actions/checkout@v4
+      with:
+        repository: stride3d/stride
+        token: ${{ secrets.GITHUB_TOKEN }}
+        path: stride
+        lfs: true
+
+    - name: Install DocFX
+      # This installs the latest version of DocFX and may introduce breaking changes
+      # run: dotnet tool update -g docfx
+      # This installs a specific, tested version of DocFX.
+      run: dotnet tool update -g docfx --version 2.76.0
+
+    - name: Build documentation
+      run: ./build-all.bat
+      working-directory: ${{ env.DOCS_PATH }}
+
+    - name: Deploy
+      uses: peaceiris/actions-gh-pages@v3.9.2
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ${{ env.DOCS_PATH }}/_site
+        publish_branch: gh-pages
diff --git a/.github/workflows/stride-docs-release-azure.yml b/.github/workflows/stride-docs-release-azure.yml
@@ -3,6 +3,11 @@
 
 name: Build Stride Docs for Azure Web App Release 🚀
 
+env:
+  COMMON_SETTINGS_PATH: en/docfx.json
+  VERSION: "2.0.0.${{ github.run_number }}"
+  DOCS_PATH: stride-docs
+
 on:
   push:
     branches:
@@ -23,22 +28,28 @@ jobs:
     runs-on: windows-2022
 
     steps:
-    # Setup .NET SDK
-    - name: Dotnet Setup
-      uses: actions/setup-dotnet@v3
+    - name: .NET SDK Setup
+      uses: actions/setup-dotnet@v4
       with:
         dotnet-version: 8.x
 
     # Checkout the Stride Docs repository from the branch that triggered the workflow
     - name: Checkout Stride Docs
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
       with:
-        path: stride-docs
+        path: ${{ env.DOCS_PATH }}
         lfs: true
 
+    - name: Set Version in docfx.json
+      run: |
+        $settingsContent = Get-Content -Path "${{ env.DOCS_PATH }}/${{ env.COMMON_SETTINGS_PATH }}" -Raw
+        $updatedDocFxJsonContent = $settingsContent -replace '2.0.0.x', "${{ env.VERSION }}"
+        Set-Content -Path "${{ env.DOCS_PATH }}/${{ env.COMMON_SETTINGS_PATH }}" -Value $updatedDocFxJsonContent
+      shell: pwsh
+
     # Checkout the Stride repository from the default branch
     - name: Checkout Stride (note the LFS)
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
       with:
         repository: stride3d/stride
         token: ${{ secrets.GITHUB_TOKEN }}
@@ -49,46 +60,53 @@ jobs:
       # This installs the latest version of DocFX and may introduce breaking changes
       # run: dotnet tool update -g docfx
       # This installs a specific, tested version of DocFX.
-      run: dotnet tool update -g docfx --version 2.74.0
+      run: dotnet tool update -g docfx --version 2.76.0
 
     - name: Build documentation
       run: ./build-all.bat
-      working-directory: stride-docs
+      working-directory: ${{ env.DOCS_PATH }}
 
     - name: Compress artifact
-      run: 7z a -r DocFX-app.zip ./stride-docs/_site/*
+      run: 7z a -r DocFX-app.zip ./${{ env.DOCS_PATH }}/_site/*
 
     - name: Upload artifact for deployment job
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: DocFX-app
         path: DocFX-app.zip
 
+    - name: Create GitHub Release
+      run: |
+        gh release create ${{ env.VERSION }} --title "v${{ env.VERSION }}" --notes "Release notes for ${{ env.VERSION }}" --draft
+      env:
+        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
   deploy:
     if: github.repository == 'stride3d/stride-docs'
     runs-on: windows-2022
+
     needs: build
     environment:
       name: 'Production'
       url: ${{ steps.deploy-to-webapp.outputs.webapp-url }}
 
     steps:
-      - name: Download artifact from build job
-        uses: actions/download-artifact@v3
-        with:
-          name: DocFX-app
-
-      # - name: List current directory
-      #   run: ls
-
-      - name: Decompress artifact
-        run: 7z x DocFX-app.zip "-o./stride-docs/_site"
-
-      - name: Deploy to Azure Web App
-        id: deploy-to-webapp
-        uses: azure/webapps-deploy@v2
-        with:
-          app-name: 'stride-doc'
-          slot-name: 'Production'
-          publish-profile: ${{ secrets.AZUREAPPSERVICE_PUBLISHPROFILE_4803638D673FA67D0C8650F34C4FA9D1 }}
-          package: ./stride-docs/_site
+    - name: Download artifact from build job
+      uses: actions/download-artifact@v4
+      with:
+        name: DocFX-app
+
+    # - name: List current directory
+    #   run: ls
+
+    - name: Decompress artifact
+      run: 7z x DocFX-app.zip "-o./${{ env.DOCS_PATH }}/_site"
+
+    - name: Deploy to Azure Web App
+      id: deploy-to-webapp
+      uses: azure/webapps-deploy@v2
+      with:
+        app-name: 'stride-doc'
+        slot-name: 'Production'
+        publish-profile: ${{ secrets.AZUREAPPSERVICE_PUBLISHPROFILE_4803638D673FA67D0C8650F34C4FA9D1 }}
+        package: ./${{ env.DOCS_PATH }}/_site
diff --git a/.github/workflows/stride-docs-release-fast-track-azure.yml b/.github/workflows/stride-docs-release-fast-track-azure.yml
@@ -4,6 +4,11 @@
 # The Fast Track skips creating artifacts and compressing them
 name: Build Stride Docs (Fast Track) for Azure Web App Release 🚀
 
+env:
+  COMMON_SETTINGS_PATH: en/docfx.json
+  VERSION: "2.0.0.${{ github.run_number }}"
+  DOCS_PATH: stride-docs
+
 on:
   workflow_dispatch:
 
@@ -12,26 +17,33 @@ jobs:
     # Run this job only if the repository is 'stride3d/stride-docs'
     if: github.repository == 'stride3d/stride-docs'
     runs-on: windows-2022
+
     environment:
       name: 'Production'
 
     steps:
-    # Setup .NET SDK
-    - name: Dotnet Setup
-      uses: actions/setup-dotnet@v3
+    - name: .NET SDK Setup
+      uses: actions/setup-dotnet@v4
       with:
         dotnet-version: 8.x
 
     # Checkout the Stride Docs repository from the branch that triggered the workflow
     - name: Checkout Stride Docs
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
       with:
-        path: stride-docs
+        path: ${{ env.DOCS_PATH }}
         lfs: true
 
+    - name: Set Version in docfx.json
+      run: |
+        $settingsContent = Get-Content -Path "${{ env.DOCS_PATH }}/${{ env.COMMON_SETTINGS_PATH }}" -Raw
+        $updatedDocFxJsonContent = $settingsContent -replace '2.0.0.x', "${{ env.VERSION }}"
+        Set-Content -Path "${{ env.DOCS_PATH }}/${{ env.COMMON_SETTINGS_PATH }}" -Value $updatedDocFxJsonContent
+      shell: pwsh
+
     # Checkout the Stride repository from the default branch
     - name: Checkout Stride (note the LFS)
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
       with:
         repository: stride3d/stride
         token: ${{ secrets.GITHUB_TOKEN }}
@@ -42,17 +54,17 @@ jobs:
       # This installs the latest version of DocFX and may introduce breaking changes
       # run: dotnet tool update -g docfx
       # This installs a specific, tested version of DocFX.
-      run: dotnet tool update -g docfx --version 2.74.0
+      run: dotnet tool update -g docfx --version 2.76.0
 
     - name: Build documentation
       run: ./build-all.bat
-      working-directory: stride-docs
+      working-directory: ${{ env.DOCS_PATH }}
 
     - name: Deploy to Azure Web App
       id: deploy-to-webapp
       uses: azure/webapps-deploy@v2
       with:
-          app-name: 'stride-doc'
-          slot-name: 'Production'
-          publish-profile: ${{ secrets.AZUREAPPSERVICE_PUBLISHPROFILE_4803638D673FA67D0C8650F34C4FA9D1 }}
-          package: ./stride-docs/_site
+        app-name: 'stride-doc'
+        slot-name: 'Production'
+        publish-profile: ${{ secrets.AZUREAPPSERVICE_PUBLISHPROFILE_4803638D673FA67D0C8650F34C4FA9D1 }}
+        package: ./${{ env.DOCS_PATH }}/_site