Merge pull request #174 from stride3d/master

Thank you everyone for your docs contribution.

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

@@ -49,7 +49,7 @@ 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.70.4
+      run: dotnet tool update -g docfx --version 2.71.0
 
     - name: Build documentation
       run: ./build-all.bat

.github/workflows/stride-docs-release-fast-track-azure.yml

@@ -42,7 +42,7 @@ 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.70.4
+      run: dotnet tool update -g docfx --version 2.71.0
 
     - name: Build documentation
       run: ./build-all.bat

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

@@ -49,7 +49,7 @@ 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.70.4
+      run: dotnet tool update -g docfx --version 2.71.0
 
     - name: Build documentation
       run: ./build-all.bat

.github/workflows/stride-docs-staging-fast-track-azure.yml

@@ -42,7 +42,7 @@ 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.70.4
+      run: dotnet tool update -g docfx --version 2.71.0
 
     - name: Build documentation
       run: ./build-all.bat

BuildDocs.ps1

@@ -83,22 +83,26 @@ function Ask-IncludeAPI {
     Write-Host ""
     Write-Host -ForegroundColor Cyan "Do you want to include API?"
     Write-Host ""
-    Write-Host -ForegroundColor Yellow "  [Y] Yes"
+    Write-Host -ForegroundColor Yellow "  [Y] Yes or ENTER"
     Write-Host -ForegroundColor Yellow "  [N] No"
     Write-Host ""
 
-    return (Read-Host -Prompt "Your choice (Y/N)").ToLower() -eq "y"
+    $answer = Read-Host -Prompt "Your choice [Y, N, or ENTER (default is Y)]"
+
+    return ($answer -ieq "y" -or $answer -eq "")
 }
 
 function Ask-UseExistingAPI {
     Write-Host ""
     Write-Host -ForegroundColor Cyan "Do you want to use already generated API metadata?"
     Write-Host ""
-    Write-Host -ForegroundColor Yellow "  [Y] Yes"
+    Write-Host -ForegroundColor Yellow "  [Y] Yes or ENTER"
     Write-Host -ForegroundColor Yellow "  [N] No"
     Write-Host ""
 
-    return (Read-Host -Prompt "Your choice (Y/N)").ToLower() -eq "y"
+    $answer = Read-Host -Prompt "Your choice [Y, N, or ENTER (default is Y)]"
+
+    return ($answer -ieq "y" -or $answer -eq "")
 }
 
 function Copy-ExtraItems {
@@ -446,8 +450,15 @@ else {
     {
         $API = Ask-IncludeAPI
 
-        if ($API) {
-            $ReuseAPI = Ask-UseExistingAPI
+        if ($API)
+        {
+            # Check for .yml files
+            $ymlFiles = Get-ChildItem -Path "en/api/" -Filter "*.yml"
+
+            if ($ymlFiles.Count -gt 0)
+            {
+                $ReuseAPI = Ask-UseExistingAPI
+            }
         }
 
     } elseif ($isCanceled) {

README.md

@@ -1,10 +1,11 @@
 # Stride Docs Development
 
-Welcome to the Stride Docs repository. This repository contains all the source files for the Stride documentation http://doc.stride3d.net/.
+Welcome to the Stride Docs repository. This repository contains all the source files for the Stride documentation https://doc.stride3d.net/.
 
 * [Getting Started](#-getting-started)
 * [Contributing](#-contributing)
 * [Roadmap](#%EF%B8%8F-roadmap)
+* [Stride Documentation Landscape](#-stride-documentation-landscape)
 * [.NET Foundation](#-net-foundation)
 * [License](#%EF%B8%8Flicense)
 
@@ -37,6 +38,16 @@ The staging website is available at https://stride-doc-staging.azurewebsites.net
 
 Our Wiki [Roadmap](https://github.com/stride3d/stride-docs/wiki/Roadmap) communicates upcoming changes to the Stride Docs.
 
+## 📖 Stride Documentation Landscape
+
+The Stride documentation landscape is organized across different repositories and their respective wikis to cater to both users and contributors. Here's how it's structured:
+
+1. [Stride Website](https://www.stride3d.net/) - Stride's official site showcasing its free, open-source 2D and 3D game engine, alongside blog posts
+   - [Stride Website Wiki](https://github.com/stride3d/stride-website/wiki) - This wiki serves as a comprehensive guide for those looking to contribute to or develop the Stride Website
+1. [Stride Docs](https://doc.stride3d.net/) - Here you'll find Stride's documentation, including manuals, tutorials, and API references
+   - [Stride Docs Wiki](https://github.com/stride3d/stride-docs/wiki) - This wiki is a comprehensive guide for individuals interested in contributing to or developing the Stride Docs
+1. [Stride Wiki](https://github.com/stride3d/stride/wiki) - A thorough guide for those who wish to contribute to or develop Stride game engine  
+
 ## 🌐 .NET Foundation
 
 This project is supported by the [.NET Foundation](http://www.dotnetfoundation.org).
@@ -47,18 +58,3 @@ For more information see the [.NET Foundation Code of Conduct](http://www.dotnet
 ## 🛡️License
 
 This project is licensed under the [MIT](https://github.com/stride3d/stride-docs/blob/master/LICENSE.md) License.
-
-## Post-Release Features
-- Dark Theme by Default
-
-## Past Content - ToDo: Review
-
-Anyone is welcome to contribute! Before you start, please take the time to read the [guidelines](GUIDELINES.md). 
-
-You can find basic information about editing the documentation in [Getting Started](GETTINGSTARTED.md) dedicated page.
-
-Don't forget to change `$version` in [deploy.ps1](build/deploy.ps1) when branching before first deployment.
-
-### Manage multiple Stride versions
-
-Each Stride minor version (i.e. 4.0, 4.1, etc.) should have its own branch, named in the fashion `master-<version>`. The only exception is latest version, which should be `master`.

en/diagnostics/STRDIAG000.md

@@ -0,0 +1,56 @@
+# Diagnostics Warning STRDIAG000
+
+> There is an Attribute Contradiction on '{0}' Member. `[DataMemberIgnore]` Attribute on a `[DataMember]` is not supported.
+> Except if it has also `[DataMemberUpdatable]` Attribute.
+
+## Explanation
+
+Adding @Stride.Core.DataMemberAttribute and @Stride.Core.DataMemberIgnoreAttribute to the same member is not supported. This would be a contradiction.
+It would mean the serializer should serialize the member and ignore it at the same time. The @Stride.Updater.DataMemberUpdatableAttribute  makes the combination valid again as it negates the @Stride.Core.DataMemberIgnoreAttribute for the binary serializer.
+
+## Example: Invalid cases
+
+The following example generates STRDIAG000 on each property:
+
+```csharp
+// STRDIAG000.cs
+using Stride.Core;
+
+public class STRDIAG000
+{
+    [DataMember]
+    [DataMemberIgnore]
+    public int Value { get; set; }
+
+    [DataMember]
+    [DataMemberIgnore]
+    public int Value;
+}
+```
+
+## Example: Special Case `DataMemberUpdatable`
+
+> [!IMPORTANT]
+> There is a special case if the @Stride.Updater.DataMemberUpdatableAttribute is applied.
+> This Attribute negates the @Stride.Core.DataMemberIgnoreAttribute for the binary Serializer, so it becomes valid again.
+
+```csharp
+using Stride.Core;
+
+public class STRDIAG000
+{
+    [DataMember]
+    [DataMemberIgnore]
+    [DataMemberUpdatable]
+    public int Value { get; set; }
+}
+```
+
+## Solution
+
+> To resolve the warning, pick either the @Stride.Core.DataMemberAttribute or the @Stride.Core.DataMemberIgnoreAttribute.
+If the `YamlSerializer` and the Editor should ignore the member but the binary serializer not, then add the @Stride.Core.DataMemberIgnoreAttribute.
+
+## References
+
+- [Serialisation](../manual/scripts/serialization.md)

en/diagnostics/STRDIAG001.md

@@ -0,0 +1,40 @@
+# Diagnostics Warning STRDIAG001
+
+> The `[DataContract]` is not valid for the type '{0}'. Expected is a public/internal Accessor.
+
+## Explanation
+
+The @Stride.Core.DataContractAttribute can only be applied to `public`/`internal` type. Any lower access will cause STRDIAG001 on the target type.
+
+## Example: private inner class
+
+The following example generates STRDIAG001:
+
+```csharp
+using Stride.Core;
+
+public class STRDIAG001
+{
+    [DataContract]
+    private class InnerClass { }
+}
+```
+
+## Example: file scoped class
+
+```csharp
+using Stride.Core;
+
+[DataContract]
+file class STRDIAG001
+{
+}
+```
+
+## Solution
+
+To resolve the warning, increase the accessibility of the type to `public`/`internal` or remove the @Stride.Core.DataContractAttribute.
+
+## References
+
+- [Serialisation](../manual/scripts/serialization.md)

en/diagnostics/STRDIAG002.md

@@ -0,0 +1,30 @@
+# Diagnostics Warning STRDIAG002
+
+> The 'DataMemberMode.Content' is not valid for the member '{0}'.
+> Only mutable reference types are supported for 'DataMemberMode.Content' Mode members.
+
+## Explanation
+
+The [DataMemberMode.Content](xref:Stride.Core.DataMemberMode) mutates the object which is currently in the member.
+As this is not possible with the current serializers, only mutable types are supported for `DataMemberMode.Content`. Immutable types in this context are none reference types and string.
+
+## Example
+
+The following example generates STRDIAG002 on each property:
+
+```csharp
+using Stride.Core;
+
+public class STRDIAG002
+{
+    [DataMember(DataMemberMode.Content)]
+    public int Value { get; set; }
+
+    [DataMember(DataMemberMode.Content)]
+    public string Value;
+}
+```
+
+## Solution
+
+To resolve the warning, pick either a reference type for the member or use `DataMemberMode.Assign` for Immutable types.

en/diagnostics/STRDIAG003.md

@@ -0,0 +1,32 @@
+# Diagnostics Warning STRDIAG003
+
+> The member '{0}' with `[DataMember]` is not accessible to the serializer. Only public/internal/internal > protected visibility is supported, when the `[DataMember]` attribute is applied.
+
+## Explanation
+
+The serialization concept in Stride expects `public`/`internal`/`internal protected` visibility of properties. Other accessibility won't be considered for serialization.
+To count `internal`/`internal protected` as visible to the Editor the @Stride.Core.DataMemberAttribute has to be applied, else it's considered as not visible.
+
+## Example
+
+The following example generates STRDIAG003 on each property:
+
+```csharp
+using Stride.Core;
+
+public class STRDIAG003
+{
+    [DataMember]
+    private int Value { get; set; }
+
+    [DataMember]
+    protected string Value;
+
+    [DataMember]
+    private protected string Value;
+}
+```
+
+## Solution
+
+To resolve the warning, increase the Accessibility to `public`/`internal`/`internal protected` of the member or remove the @Stride.Core.DataMemberAttribute Attribute.

en/diagnostics/STRDIAG004.md

@@ -0,0 +1,66 @@
+# Diagnostics Warning STRDIAG004
+
+> 1. The property '{0}' with `[DataMember]` does not have a getter which is required for serialization.
+> 2. The property '{0}' with `[DataMember]` does not have an accessible getter which is required for serialization. A public/internal/internal protected getter is expected.
+
+## Explanation
+
+All serializers need a getter on a property to be able to get the content of the property.
+This is required for all serializers in Stride.
+- Non existent getters will result in error message 1.
+- Non visible getters will result in error message 2.
+
+## Example
+
+The following example generates STRDIAG004 on each property:
+
+```csharp
+using Stride.Core;
+
+public class STRDIAG004
+{
+    // throws Diagnostics message 1
+    [DataMember]
+    public int Value { set;}
+
+    // throws Diagnostics message 2
+    [DataMember]
+    public string Value { private get; set; }
+
+    // throws Diagnostics message 2 
+    [DataMember]
+    public string Value { protected get; set; }
+}
+```
+
+> [!WARNING]
+> There is an edge case with `internal`/`internal protected`, it will count as non visible when the @Stride.Core.DataMemberAttribute isn't applied.
+> But when the attribute is applied then the getter counts as visible and therefore is correct.
+
+```csharp
+// STRDIAG000.cs
+using Stride.Core;
+
+public class STRDIAG004
+{
+    // will throw STRDIAG004
+    public int Value { internal get; set; }
+
+    // will throw STRDIAG004
+    public int Value { internal protected get; set; }
+
+    // won't throw STRDIAG004
+    [DataMember]
+    public string Value { internal get; set; }
+
+    // won't throw STRDIAG004
+    [DataMember]
+    public string Value { internal protected get; set; }
+}
+```
+
+## Solution
+
+To resolve the warning 1, add a getter to the property with a `public`/`internal`/`internal protected` accessibility or remove the @Stride.Core.DataMemberAttribute .
+
+To resolve the warning 2, increase the accessibility of the property getter to `public`/`internal`/`internal protected` accessibility or remove the @Stride.Core.DataMemberAttribute .

en/diagnostics/STRDIAG005.md

@@ -0,0 +1,31 @@
+# Diagnostics Warning STRDIAG005
+
+> The `[DataMember]` Attribute is applied to a read-only member '{0}' with a non supported type. Only mutable reference types are supported for read-only members.
+
+## Explanation
+
+Having no set possibility automatically lets the serializers automatically use the [DataMemberMode.Content](xref:Stride.Core.DataMemberMode).
+For immutable types the `DataMemberMode.Content` is never valid.
+Immutable types in this context are none reference types and string.
+
+## Example
+
+The following example generates STRDIAG005 on each property:
+
+```csharp
+using Stride.Core;
+
+public class STRDIAG005
+{
+    [DataMember]
+    public readonly int Value;
+    [DataMember]
+    public string Value { get; }
+}
+```
+
+## Solution
+
+To resolve the warning for fields, remove the `[DataMember]` attribute or remove the `readonly` modifier.
+
+To resolve the warning for properties, alter the type of the property to a supported type or remove the `[DataMember]` attribute.