Merge pull request #214 from VaclavElias/update-15-contributors-deployment-docs-improvements

Update 15 - Contributors deployment docs improvements

.github/workflows/stride-docs-github.yml

@@ -0,0 +1,44 @@
+# More GitHub Actions for Azure: https://github.com/Azure/actions
+
+name: Build Stride Docs for GitHub Staging
+
+on:
+  workflow_dispatch:
+
+jobs:
+  publish-docs:
+    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/[email protected]
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: stride-docs/_site
+          publish_branch: gh-pages

Stride.Docs.sln

@@ -7,6 +7,7 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Stride.Docs", "Stride.Docs.
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{85103FBF-C9A6-4722-B36B-89A58F55C1DF}"
 	ProjectSection(SolutionItems) = preProject
+		.github\workflows\stride-docs-github.yml = .github\workflows\stride-docs-github.yml
 		.github\workflows\stride-docs-release-azure.yml = .github\workflows\stride-docs-release-azure.yml
 		.github\workflows\stride-docs-release-fast-track-azure.yml = .github\workflows\stride-docs-release-fast-track-azure.yml
 		.github\workflows\stride-docs-staging-azure.yml = .github\workflows\stride-docs-staging-azure.yml

en/contributors/documentation/deployment-azure.md

@@ -6,8 +6,10 @@ Our team has explored various deployment options, ultimately selecting the metho
 
 This guide is crafted for individuals who already have access to the Azure subscription. It provides step-by-step instructions for setting up a new Azure Web App, specifically tailored for staging environments. Note that the process for setting up a production environment is similar, but requires a distinct web app name.
 
+Deployments to Azure Web Apps are automated through GitHub Actions, forming an integral part of our Continuous Integration/Continuous Deployment (CI/CD) process. The CI/CD pipeline is configured to automatically trigger deployments upon merging changes into either the `staging` or `release` branches.
+
 > [!NOTE]
-> The deployment process outlined here is already established and running, hosted on Azure and sponsored by the .NET Foundation. This guide serves primarily as a reference for maintainers in the event that a new deployment setup is required.
+> The deployment process outlined here is already established and running, hosted on Azure and sponsored by the .NET Foundation. This guide serves primarily as a reference for maintainers in the event that a new deployment setup is required. 
 
 ### Setting up a new Azure Web App
 
@@ -77,6 +79,15 @@ The previous step will have added a GitHub Action to your repository, which migh
 1. This workflow might also need to be added to the `master` branch if it is not already present.
 1. Execute the workflow `stride-docs-staging-azure.yml`. Ensure you select the correct branch `staging` and click **Run workflow**. This action will deploy the website to the Azure Web App.
 
+### GitHub Actions
+
+- `stride-website-github.yml`: Enables manual deployment to GitHub Pages in a forked repository, primarily for showcasing updates.
+- `stride-docs-release-azure.yml`: Automates deployment to production upon merging changes into the `release` branch, with a manual trigger option also available.
+- `stride-docs-release-fast-track-azure.yml`: Provides manual deployment to production, bypassing the creation of artifacts.
+- `stride-docs-staging-azure.yml`: Facilitates automatic deployment to [staging](https://stride-doc-staging.azurewebsites.net/latest/en/index.html) when changes are merged into the `staging` branch, and includes a manual trigger option.
+- `stride-docs-staging-fast-track-azure.yml`: Allows for manual deployment to staging, skipping the creation of artifacts.
+- `stride-website-wiki.yml`: Deploys automatically to the GitHub Wiki upon changes being pushed to the `wiki` folder, with a manual trigger feature also available.
+
 ## Deployment to GitHub Pages
 
 To showcase your updates, especially helpful for design changes pending review, you can deploy the docs website either to your infrastructure or to GitHub Pages, a free hosting service. Once deployed, share the link with us for review.

en/contributors/documentation/docfx.md

@@ -50,57 +50,36 @@ The folder structure plays a vital role in the documentation generation process,
 
 ### Files
 
-- `en\*.md` - Markdown content pages
-- `en\*.yml` - Table of content files
-- `en\.nojekyll` - GitHub Action flag
-- `en\docfx.json` - Docfx configuration file
-- `en\filterConfig.yml` - API exclusion rules
-- `en\languages.json` - Languages configuration
-
-### Non Docfx files
-
-- `appsettings.json` - ASP.NET Core configuration file
-- `appsettings.Development.json` - ASP.NET Core configuration file
-- `build-all.bat` - 
-- `BuildDocs.ps1` - 
-- `OldDocsFix.ps1` - 
-- `Program.cs` - ASP.NET Core startup file
-- `run.bat` - 
-- `run-fix.bat` - 
-- `Stride.Docs.csproj` - ASP.NET Core project file
-- `Stride.Docs.sln` - ASP.NET Core solution file
-- `Stride.Docs.csproj.user` - ASP.NET Core project file
-- `versions.json` - 
-- `web.config` - Configuration file for IIS deployment
+- `en\*.md`: Markdown content pages
+- `en\*.yml`: Table of content files
+- `en\.nojekyll`: A flag file for GitHub Actions
+- `en\docfx.json`: Docfx configuration file
+- `en\filterConfig.yml`: Rules for API exclusion
+- `en\languages.json`: Configuration file for languages
+
+### Non Docfx Files
+
+- `appsettings.json`: Configuration file for ASP.NET Core.
+- `appsettings.Development.json`: Development-specific configuration file for ASP.NET Core.
+- `build-all.bat`: Batch file used in GitHub Actions CI/CD to build all documentation using `BuildDocs.ps1`.
+- `BuildDocs.ps1`: PowerShell script responsible for building documentation. Refer to [pipeline](documentation-generation-pipeline.md) for details.
+- `OldDocsFix.ps1`: Temporary PowerShell script for fixing old documentation.
+- `Program.cs`: Startup file for ASP.NET Core.
+- `run.bat`: Batch file to run `BuildDocs.ps1` in interactive mode.
+- `run-fix.bat`: Temporary batch file to run `OldDocsFix.ps1`.
+- `Stride.Docs.csproj`: ASP.NET Core project file.
+- `Stride.Docs.sln`: ASP.NET Core solution file.
+- `Stride.Docs.csproj.user`: User-specific ASP.NET Core project file.
+- `versions.json`: Configuration file managing versions of Stride documentation.
+- `web.config`: Configuration file for IIS deployment.
 
 > [!NOTE]
-> This project includes Visual Studio solution so you can edit the files from the Visual Studio IDE.
+> This project includes the Visual Studio solution `Stride.Docs.sln`, allowing you to edit the files using the Visual Studio IDE.
 
 ## Layouts
 
-All the layouts are located in the `/_layouts` folder. The `default` layout is the main layout page and is used by all the other layouts. 
-
-- `default` - Main layout page
-- `container` - Used by some pages
-- `page` - Used by most of the pages
-- `post` - Used by blog posts
+We utilize the default layout provided by the `modern` template, as specified in `docfx.json`.
 
 ## Includes
 
-All the includes are located in the `/_includes` folder. The includes are reusable code snippets that can be included in multiple pages.
-
-Some includes are used solely by the layouts, while others are used by the content pages.
-
-## Advanced Topics
-
-### Creating Custom Shortcodes and Includes
-
-If you need to create a custom shortcode or include, please follow the existing structure and [include a comment](content.md#shortcodes-and-includes) to explain the new shortcode or include.
-
-The shortcodes are defined in the `.eleventy.js` file, while the includes are located in the `/_includes` folder.
-
-You can explore the existing shortcodes and includes to get a better understanding of how they work and how to create new ones.
-
-### Performance Optimization
-
-ToDo: Remove this section if not needed
+All includes are located in the `/_includes` folder. These are reusable markdown snippets that can be incorporated into multiple pages.

en/contributors/website/deployment-azure.md

@@ -6,8 +6,10 @@ Our team has explored various deployment options, ultimately selecting the metho
 
 This guide is crafted for individuals who already have access to the Azure subscription. It provides step-by-step instructions for setting up a new Azure Web App, specifically tailored for staging environments. Note that the process for setting up a production environment is similar, but requires a distinct web app name.
 
+Deployments to Azure Web Apps are automated through GitHub Actions, forming an integral part of our Continuous Integration/Continuous Deployment (CI/CD) process. The CI/CD pipeline is configured to automatically trigger deployments upon merging changes into either the `staging` or `release` branches.
+
 > [!NOTE]
-> The deployment process outlined here is already established and running, hosted on Azure and sponsored by the .NET Foundation. This guide serves primarily as a reference for maintainers in the event that a new deployment setup is required.
+> The deployment process outlined here is already established and running, hosted on Azure and sponsored by the .NET Foundation. This guide serves primarily as a reference for maintainers in the event that a new deployment setup is required. 
 
 ### Setting up a new Azure Web App
 
@@ -77,6 +79,13 @@ The previous step will have added a GitHub Action to your repository, which migh
 1. This workflow might also need to be added to the `master` branch if it is not already present.
 1. Execute the workflow `stride-website-staging-azure.yml`. Ensure you select the correct branch `staging` and click **Run workflow**. This action will deploy the website to the Azure Web App.
 
+### GitHub Actions
+
+- `stride-website-github.yml`: Facilitates manual deployment to GitHub Pages in the forked repository, primarily used for showcasing updates
+- `stride-website-release-azure.yml`: Automates deployment to production upon merging changes into `release` branch, with a manual trigger option also available
+- `stride-website-staging-azure.yml`: Enables automatic deployment to [staging](https://stride-website-staging.azurewebsites.net/) upon merging changes into `staging` branch, along with an option for manual triggering
+- `stride-website-wiki.yml`: Automatically deploys to the GitHub Wiki when changes are pushed to the `wiki` folder in the `master` branch, also includes a manual trigger feature
+
 ## Deployment to GitHub Pages
 
 To showcase your updates, especially helpful for design changes pending review, you can deploy the website either to your infrastructure or to GitHub Pages, a free hosting service. Once deployed, share the link with us for review.