Merge pull request #297 from stride3d/master

Initiating deployment of latest docs updates to staging
stride3d · Jun 5, 2024 · 99f994b · 99f994b
2 parents f9755ad + 4e183d8
commit 99f994b
Show file tree

Hide file tree

Showing 24 changed files with 222 additions and 131 deletions.
diff --git a/.github/release.yml b/.github/release.yml
@@ -2,6 +2,7 @@ changelog:
   exclude:
     labels:
       - ignore-for-release
+      - deployment
     authors:
       - dependabot
   categories:

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,8 +15,7 @@ jobs:
     runs-on: windows-2022
 
     steps:
-    # Setup .NET SDK
-    - name: Dotnet Setup
+    - name: .NET SDK Setup
       uses: actions/setup-dotnet@v4
       with:
         dotnet-version: 8.x
@@ -20,9 +24,16 @@ jobs:
     - name: Checkout Stride Docs
       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@v4
@@ -40,11 +51,11 @@ jobs:
 
     - name: Build documentation
       run: ./build-all.bat
-      working-directory: stride-docs
+      working-directory: ${{ env.DOCS_PATH }}
 
     - name: Deploy
       uses: peaceiris/actions-gh-pages@v3.9.2
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: stride-docs/_site
+        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,8 +28,7 @@ jobs:
     runs-on: windows-2022
 
     steps:
-    # Setup .NET SDK
-    - name: Dotnet Setup
+    - name: .NET SDK Setup
       uses: actions/setup-dotnet@v4
       with:
         dotnet-version: 8.x
@@ -33,9 +37,16 @@ jobs:
     - name: Checkout Stride Docs
       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@v4
@@ -53,17 +64,24 @@ jobs:
 
     - 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@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 }}
+      working-directory: ${{ env.DOCS_PATH }}
+
   deploy:
     if: github.repository == 'stride3d/stride-docs'
     runs-on: windows-2022
@@ -83,7 +101,7 @@ jobs:
     #   run: ls
 
     - name: Decompress artifact
-      run: 7z x DocFX-app.zip "-o./stride-docs/_site"
+      run: 7z x DocFX-app.zip "-o./${{ env.DOCS_PATH }}/_site"
 
     - name: Deploy to Azure Web App
       id: deploy-to-webapp
@@ -92,4 +110,4 @@ jobs:
         app-name: 'stride-doc'
         slot-name: 'Production'
         publish-profile: ${{ secrets.AZUREAPPSERVICE_PUBLISHPROFILE_4803638D673FA67D0C8650F34C4FA9D1 }}
-        package: ./stride-docs/_site
+        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:
 
@@ -17,8 +22,7 @@ jobs:
       name: 'Production'
 
     steps:
-    # Setup .NET SDK
-    - name: Dotnet Setup
+    - name: .NET SDK Setup
       uses: actions/setup-dotnet@v4
       with:
         dotnet-version: 8.x
@@ -27,9 +31,16 @@ jobs:
     - name: Checkout Stride Docs
       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@v4
@@ -47,7 +58,7 @@ jobs:
 
     - 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
@@ -56,4 +67,4 @@ jobs:
         app-name: 'stride-doc'
         slot-name: 'Production'
         publish-profile: ${{ secrets.AZUREAPPSERVICE_PUBLISHPROFILE_4803638D673FA67D0C8650F34C4FA9D1 }}
-        package: ./stride-docs/_site
+        package: ./${{ env.DOCS_PATH }}/_site
diff --git a/.github/workflows/stride-docs-staging-fast-track-azure.yml b/.github/workflows/stride-docs-staging-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 Staging
 
+env:
+  COMMON_SETTINGS_PATH: en/docfx.json
+  VERSION: "2.0.0.${{ github.run_number }}"
+  DOCS_PATH: stride-docs
+
 on:
   workflow_dispatch:
 
@@ -17,8 +22,7 @@ jobs:
       name: 'Production'
 
     steps:
-    # Setup .NET SDK
-    - name: Dotnet Setup
+    - name: .NET SDK Setup
       uses: actions/setup-dotnet@v4
       with:
         dotnet-version: 8.x
@@ -27,9 +31,16 @@ jobs:
     - name: Checkout Stride Docs
       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@v4
@@ -47,7 +58,7 @@ jobs:
 
     - 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
@@ -56,4 +67,4 @@ jobs:
         app-name: 'stride-doc'
         slot-name: 'staging'
         publish-profile: ${{ secrets.AZUREAPPSERVICE_PUBLISHPROFILE_32FCD402B970463A9143B24C9B225749 }}
-        package: ./stride-docs/_site
+        package: ./${{ env.DOCS_PATH }}/_site
diff --git a/BuildDocs.ps1 b/BuildDocs.ps1
@@ -15,12 +15,16 @@
     Switch parameter. If provided, the script will build documentation in all available languages and include API documentation.
 .PARAMETER Version
     The Version to build the Docs, the default is the latest version
+.PARAMETER SkipPdfBuilding
+    Switch parameter. If provided, It skips Pdf generation step.
 .EXAMPLE
     .\BuildDocs.ps1 -BuildAll
     In this example, the script will build the documentation in all available languages and include API documentation. Use this in GitHub Actions.
 .EXAMPLE
     .\BuildDocs.ps1
     In this example, the script will prompt the user to select an operation and an optional language. If the user chooses to build the documentation, the script will also ask if they want to include API documentation.
+.EXAMPLE
+    .\BuildDocs.ps1 -SkipPdfBuilding
 #>
 
 param (
@@ -30,6 +34,7 @@ param (
         param([string] $CommandName,[string] $ParameterName,[string] $WordToComplete,[System.Management.Automation.Language.CommandAst] $CommandAst,[System.Collections.IDictionary] $FakeBoundParameters)
         return (Get-Content $PSScriptRoot\versions.json -Encoding UTF8 | ConvertFrom-Json).versions
     })]
+    [switch]$SkipPdfBuilding,
     $Version = $((Get-Content $PSScriptRoot\versions.json -Encoding UTF8 | ConvertFrom-Json).versions | Sort-Object -Descending | Select-Object -First 1)
 )
 
@@ -189,12 +194,23 @@ function Build-EnglishDoc {
     # Output to both build.log and console
     docfx build en/docfx.json -o $outputDirectory | Write-Host
 
-    # Build pdf files
-    docfx pdf en/docfx.json -o $outputDirectory | Write-Host
+    Build-EnglishPdf -SkipBuilding $SkipPdfBuilding
 
     return $LastExitCode
 }
 
+function Build-EnglishPdf
+{
+    param (
+        $SkipBuilding
+    )
+    if(!$SkipBuilding)
+    {
+        # Build pdf files
+        docfx pdf en/docfx.json -o $outputDirectory | Write-Host
+    }
+}
+
 function Build-NonEnglishDoc {
     param (
         $SelectedLanguage
@@ -219,12 +235,12 @@ function Build-NonEnglishDoc {
         # Copy all files from en folder to the selected language folder, this way we can keep en files that are not translated
         Copy-Item en/* -Recurse $langFolder -Force
 
-        # Get all translated files from the selected language folder
+        # Get all previously copied en files from the selected language folder
         $files = Get-ChildItem "$langFolder/$($Settings.ManualFolderName)/*.md" -Recurse -Force
 
         Write-Host "Start write files:"
 
-        # Mark files as not translated if they are not in the toc.md file
+        # Mark files as not translated if they are not a toc.md file
         foreach ($file in $files)
         {
             if($file.ToString().Contains("toc.md")) {

diff --git a/en/community-resources/physics.md b/en/community-resources/physics.md
@@ -3,4 +3,3 @@
 * [Bepu physics integration](https://github.com/Nicogo1705/BepuPhysicIntegrationTest/tree/master)
 * [Trigger Example](https://github.com/profan/XenkoByteSized#xenkobytesizedtriggerscene---doorscript)
 * [Vehicle Script](https://github.com/profan/XenkoByteSized#xenkobytesizedvehiclescene---vehiclescript)
-* [XenkoRotatingSun](https://github.com/SuavePirate/Xenko.RotatingSun) - Rotating Sun
diff --git a/en/diagnostics/STRDIAG010.md b/en/diagnostics/STRDIAG010.md
@@ -0,0 +1,50 @@
+# Diagnostics Warning STRDIAG010
+
+> The Type '{0}' doesn't have a public parameterless constructor, which is needed for Serialization.
+
+## Explanation
+
+By default, Stride serializers only support types that have a parameterless constructor. If no constructor is defined then the default constructor counts as parameterless constructor. Primary Constructors with parameters count as non parameterless constructor. Structs have per default a parameterless constructor so this warning will never appear on a struct.
+
+## Example
+
+The following example generates STRDIAG010:
+
+```csharp
+using Stride.Core;
+
+[DataContract]
+public class InvalidSTRDIAG010
+{
+    // no parameterless constructor available so it will throw STRDIAG010
+    public InvalidSTRDIAG010(int x, int y)
+    {
+
+    }
+}
+```
+
+The following example doesn't generate STRDIAG010:
+
+```csharp
+public class ValidSTRDIAG010
+{
+    // will be ignored by the serializers
+    public ValidSTRDIAG010(int x, int y)
+    {
+    }
+    // this parameterless constructor will be used by the serializers
+    public ValidSTRDIAG010()
+    {
+
+    }
+}
+```
+
+## Solution
+
+To resolve the warning, add a parameterless constructor that can be used by the serializers. Or remove the @Stride.Core.DataContractAttribute so the class gets entirely ignored by the serialization system.
+
+## References
+
+- [Serialisation](../manual/scripts/serialization.md)