Merge pull request #216 from stride3d/master

Initiating deployment of latest docs updates to staging

.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/contribution-workflow.md

@@ -0,0 +1,55 @@
+# Contribution Workflow for Stride Projects
+
+This guide outlines the fundamental workflow for contributing to various Stride projects, including the Stride Engine, Stride website, and Stride documentation. Whether you're a seasoned contributor or new to the project, this workflow ensures your contributions are effectively integrated.
+
+## Overview
+
+The contribution process involves several key steps, from forking the repository to having your changes merged into the main project. This workflow is applicable to contributions to the Stride Engine, Stride website, and Stride documentation.
+
+``` mermaid
+%% Define styles
+
+%% Main Graph
+graph TB
+
+%% Nodes
+    Start[Start]
+    A[Fork the Repository]
+    B[Create Branch 'X']
+    C[Make Updates on Branch 'X']
+    D{Has the Upstream Changed?}
+    E[Sync/Merge Upstream to Forked Main Branch]
+    F[Sync/Merge Forked Main Branch to Branch 'X']
+    G[Test your updates]
+    H["Create a Pull Request (PR)"]
+    I[Wait for the PR to be Merged]
+    J[Address PR Feedback]
+    K[Sync/Merge Upstream to Your Forked Main Branch]
+    L{Do You Want to Make More Updates?}
+    Z[End]
+
+%% Edges
+    Start --> A --> B --> C --> D
+    D -->|Yes| E
+    D -->|No| G
+    E --> F --> G
+    G --> H --> I --> J --> K --> L
+    L -->|Yes| B
+    L -->|No| Z
+```
+
+## Detailed Steps
+
+1. **Fork the Repository**: Start by forking the repository of the project you wish to contribute to
+1. **Create a Branch**: Name your branch appropriately and start making your changes
+1. **Make and Test Updates**: Implement your changes and test them within your branch
+1. **Review and Create a PR**: Review your updates and create a Pull Request to the main repository
+1. **Address Feedback**: If there is any feedback on your PR, address it to improve your contribution
+1. **Final Merging**: Once your PR is approved, it will be merged into the main project
+
+## Best Practices
+1. Ensure your updates align with the project goals and guidelines
+1. Keep your fork synchronized with the main repository to avoid conflicts
+1. Engage with the Stride community for support and collaboration
+
+For more specific guidelines related to each project, refer to their respective contribution documentation.

en/contributors/documentation/deployment-azure.md

@@ -6,6 +6,8 @@ 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.
 
@@ -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`: 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 docs website either to your infrastructure or to GitHub Pages, a free hosting service. Once deployed, share the link with us for review.
@@ -90,11 +101,21 @@ In your `stride-docs` repository:
 
 ### Run GitHub Action
 
-1. Go to **Actions**, select **Build Stride Web for GitHub Staging**
+1. Go to **Actions**, select **Build Stride Docs for GitHub Staging**
    - Click **Run workflow**; you may optionally select a branch
 2. Monitor the build logs while the action is in progress
 3. Upon successful build, a `gh-pages` branch will be created
-4. Navigate to **Settings** → **Pages**
+4. Navigate to **Settings** → **Pages** → **Branch** section
    - Choose the `gh-pages` branch with the root option and click **Save**
 5. After saving, an internal GitHub Action **pages build and deployment** is automatically created and triggered, deploying the content to the GitHub Pages website
-6. The website will be accessible at `https://[your-username].github.io/stride-docs`
+6. The website will be accessible at `https://[your-username].github.io/stride-docs/4.2/en`
+   - Change the version in the URL accordingly. You might see some JS errors, related to file expected in the root level.
+
+### Add Custom Domain
+
+Optionally, you can add also a custom domain. This should resolve JS url related errors.
+
+1. Go to **Settings** → **Pages** → **Custom domain**
+   - Enter your custom domain and follow the instructions for verification
+1. Upon saving, the **pages build and deployment** action is triggered again, adding a `CNAME` file containing your custom domain name to the `gh-pages` branch
+1. Your website should now be fully operational on your custom domain, for example, `https://stride-docs.vaclavelias.com/4.2/en/` is hosted on GitHub Pages

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/documentation/major-release-workflow.md

@@ -12,7 +12,7 @@ Assuming the transition is from version `4.1` to `4.2`, and that the Stride sour
    - `name: 4.1 release notes` with `href: ReleaseNotes-4.1.md`
 1. In `en\docfx.json`
    - `_appFooter`: Increase the version number
-   - Change `TargetFramework` to the current framework version being used. Ensure to test this step locally
+   - Change `TargetFramework`in two locations to the current framework version being used. Ensure to test this step locally
 1. Edit `versions.json`
    - Under `versions`, add the new version `4.2`
 1. For GitHub Actions deployment update `*.yml` files in the `.github\workflows\` folder

en/contributors/documentation/troubleshooting-and-faq.md

@@ -5,12 +5,11 @@
 
 # Known Issues
 
-1. **Sponsor Page - Widget Incompatibility with dark theme:** Widgets on the Sponsor Page currently do not support the dark theme. As a workaround, we can either fetch data from https://opencollective.com/stride3d/members/all.json and render it before deployment or make it dynamic. Both options would give us more control over the content and design, and allow for better compatibility with the dark theme in the future.
-1. **Search Page - Lack of pagination:** At present, the Search Page does not have pagination, which limits the maximum number of search results displayed to 100. To resolve this issue, we can implement a pager in JavaScript. This would enable users to navigate through multiple pages of search results, providing a more comprehensive view of the available content. 
+ToDo: Add any known issues
 
 # Common Issues and Solutions
 
-Any issue should be added to Stride Website [GitHub issues](https://github.com/stride3d/stride-website/issues) so it can be tracked and elaborated by the community.
+Any issue should be added to Stride Docs [GitHub issues](https://github.com/stride3d/stride-docs/issues) so it can be tracked and elaborated by the community.
 
 # Frequently Asked Questions
 

en/contributors/toc.yml

@@ -6,6 +6,8 @@ items:
   expanded: true
 - name: 💸 Donate
   href: donate.md
+- name: 🤝 Contribution Workflow
+  href: contribution-workflow.md
 - name: 🛠️ Contribute to the engine
   expanded: false
   href: engine/index.md

en/contributors/website/deployment-azure.md

@@ -6,6 +6,8 @@ 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.
 
@@ -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.