Migrate documentation to Docfx

.github/workflows/docs.yml

@@ -1,23 +1,48 @@
 name: Docs
 on:
   push:
-    branches: [ main ]
+    branches:
+      - main
+      - development
+
+permissions:
+  actions: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
 jobs:
   deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          submodules: recursive
 
-      - name: Doxygen Action
-        uses: mattnotmitt/doxygen-action@v1
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
         with:
-          doxyfile-path: "./docs/Doxyfile"
-          working-directory: "."
+          global-json-file: global.json
 
-      - name: Deploy
-        uses: peaceiris/actions-gh-pages@v4
+      - name: Install DocFX
+        run: dotnet tool update -g docfx
+
+      - name: Build Docs
+        run: docfx docfx.json
+        working-directory: docs
+
+      - name: Upload Docs
+        uses: actions/upload-pages-artifact@v3
         with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./docs/html
-          commit_message: "Automated Commit: Update docs"
+          path: 'docs/html'
+
+      - name: Deploy Docs to GitHub Pages
+        id: deploy
+        uses: actions/deploy-pages@v4

.gitignore

@@ -357,3 +357,4 @@ crashlytics.properties
 crashlytics-build.properties
 fabric.properties
 docs/html
+docs/api

NWN.Anvil.Samples/NWN.Anvil.Samples.csproj.DotSettings

@@ -0,0 +1,2 @@
+<wpf:ResourceDictionary xml:space="preserve" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" xmlns:s="clr-namespace:System;assembly=mscorlib" xmlns:ss="urn:shemas-jetbrains-com:settings-storage-xaml" xmlns:wpf="http://schemas.microsoft.com/winfx/2006/xaml/presentation">
+	<s:Boolean x:Key="/Default/CodeInspection/NamespaceProvider/NamespaceFoldersToSkip/=src_005Cmain/@EntryIndexedValue">True</s:Boolean></wpf:ResourceDictionary>

docs/samples/API/Async/NwTaskExamples.cs → NWN.Anvil.Samples/src/main/API/Async/NwTaskExamples.cs

@@ -9,7 +9,7 @@
 using Anvil.API;
 using Anvil.Services;
 
-namespace NWN.Anvil.Samples
+namespace NWN.Anvil.Samples.Async
 {
   [ServiceBinding(typeof(NwTaskExamples))]
   public class NwTaskExamples

docs/samples/API/EngineStructures/CassowaryExamples.cs → NWN.Anvil.Samples/src/main/API/EngineStructures/CassowaryExamples.cs

@@ -6,7 +6,7 @@
 using Anvil.Services;
 using NLog;
 
-namespace NWN.Anvil.Samples
+namespace NWN.Anvil.Samples.EngineStructures
 {
   [ServiceBinding(typeof(CassowaryExamples))]
   public class CassowaryExamples

docs/samples/API/EngineStructures/EffectExamples.cs → NWN.Anvil.Samples/src/main/API/EngineStructures/EffectExamples.cs

@@ -8,7 +8,7 @@
 using Anvil.API.Events;
 using Anvil.Services;
 
-namespace NWN.Anvil.Samples
+namespace NWN.Anvil.Samples.EngineStructures
 {
   [ServiceBinding(typeof(EffectExamples))]
   public class EffectExamples

docs/samples/API/EngineStructures/ItemPropertyExamples.cs → NWN.Anvil.Samples/src/main/API/EngineStructures/ItemPropertyExamples.cs

@@ -6,7 +6,7 @@
 using Anvil.API.Events;
 using Anvil.Services;
 
-namespace NWN.Anvil.Samples
+namespace NWN.Anvil.Samples.EngineStructures
 {
   [ServiceBinding(typeof(ItemPropertyExamples))]
   public class ItemPropertyExamples

docs/samples/Services/BasicScriptHandler.cs → NWN.Anvil.Samples/src/main/Services/BasicScriptHandler.cs

@@ -8,7 +8,7 @@
 
 // The "ServiceBinding" attribute indicates this class should be created on start, and available to other classes as a dependency "MyScriptHandler"
 // You can also bind yourself to an interface or base class. The system also supports multiple bindings.
-namespace NWN.Anvil.Samples
+namespace NWN.Anvil.Samples.Services
 {
   [ServiceBinding(typeof(BasicScriptHandler))]
   public class BasicScriptHandler

docs/samples/Services/ChatHandler.cs → NWN.Anvil.Samples/src/main/Services/ChatHandler.cs

@@ -8,7 +8,7 @@
 using Anvil.API.Events;
 using Anvil.Services;
 
-namespace NWN.Anvil.Samples
+namespace NWN.Anvil.Samples.Services
 {
   // Our base chat command interface...
   public interface IChatCommand

docs/samples/Services/DateTimeLocalVariable.cs → NWN.Anvil.Samples/src/main/Services/DateTimeLocalVariable.cs

@@ -7,7 +7,7 @@
 using Anvil.API;
 using NWN.Core;
 
-namespace NWN.Anvil.Samples
+namespace NWN.Anvil.Samples.Services
 {
   public class DateTimeLocalVariable : LocalVariable<DateTime>
   {

docs/samples/Services/PerformanceReportService.cs → NWN.Anvil.Samples/src/main/Services/PerformanceReportService.cs

@@ -6,7 +6,7 @@
 using Anvil.Services;
 using NLog;
 
-namespace NWN.Anvil.Samples
+namespace NWN.Anvil.Samples.Services
 {
   [ServiceBinding(typeof(IUpdateable))]
   [ServiceBinding(typeof(PerformanceReportService))]

docs/samples/Services/SchedulerServiceExample.cs → NWN.Anvil.Samples/src/main/Services/SchedulerServiceExample.cs

@@ -5,7 +5,7 @@
 using System;
 using Anvil.Services;
 
-namespace NWN.Anvil.Samples
+namespace NWN.Anvil.Samples.Services
 {
   [ServiceBinding(typeof(ScheduledService))]
   public class ScheduledService

docs/samples/Services/ServiceBindingBasics.cs → NWN.Anvil.Samples/src/main/Services/ServiceBindingBasics.cs

@@ -5,7 +5,7 @@
 using Anvil.Services;
 using NLog;
 
-namespace NWN.Anvil.Samples
+namespace NWN.Anvil.Samples.Services
 {
   // The "ServiceBinding" attribute indicates this class will be created on start, and available to other classes as "ServiceA".
   [ServiceBinding(typeof(ServiceA))]

docs/samples/Services/TriggerHandlerService.cs → NWN.Anvil.Samples/src/main/Services/TriggerHandlerService.cs

@@ -8,7 +8,7 @@
 using Anvil.Services;
 using NLog;
 
-namespace NWN.Anvil.Samples
+namespace NWN.Anvil.Samples.Services
 {
   [ServiceBinding(typeof(TriggerHandlerService))]
   public class TriggerHandlerService

docs/samples/Services/WelcomeMessageService.cs → NWN.Anvil.Samples/src/main/Services/WelcomeMessageService.cs

@@ -6,7 +6,7 @@
 using Anvil.API.Events;
 using Anvil.Services;
 
-namespace NWN.Anvil.Samples
+namespace NWN.Anvil.Samples.Services
 {
   [ServiceBinding(typeof(WelcomeMessageService))]
   public class WelcomeMessageService

docs/samples/Services/XPReportService.cs → NWN.Anvil.Samples/src/main/Services/XPReportService.cs

@@ -7,7 +7,7 @@
 using Anvil.API.Events;
 using Anvil.Services;
 
-namespace NWN.Anvil.Samples
+namespace NWN.Anvil.Samples.Services
 {
   // This is the deserialization class for this specific type of 2da.
   // We can implement our own helper functions here that operate on the 2da data, and cache it.

NWN.Anvil.sln

@@ -6,7 +6,7 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "NWN.Anvil.Tests", "NWN.Anvi
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "NWN.Anvil.TestRunner", "NWN.Anvil.TestRunner\NWN.Anvil.TestRunner.csproj", "{0FF456D7-499D-46D4-A88F-5ACE1D665EF7}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "NWN.Anvil.Samples", "docs\NWN.Anvil.Samples.csproj", "{9CB3780F-8EEE-4911-B7A3-1FD9C03F9737}"
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "NWN.Anvil.Samples", "NWN.Anvil.Samples\NWN.Anvil.Samples.csproj", "{9CB3780F-8EEE-4911-B7A3-1FD9C03F9737}"
 EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution

NWN.Anvil/src/main/API/Async/NwTask.cs

@@ -9,12 +9,12 @@
 
 namespace Anvil.API
 {
-  //! ## Examples
-  //! @include NwTaskExamples.cs
-
   /// <summary>
   /// Asynchronous tasks and helpers for running NWN APIs in an async context.
   /// </summary>
+  /// <example>
+  ///
+  /// [!code-csharp[](~/../NWN.Anvil.Samples/src/main/API/Async/NwTaskExamples.cs)]</example>
   public static class NwTask
   {
     private static readonly Logger Log = LogManager.GetCurrentClassLogger();

NWN.Anvil/src/main/API/EngineStructures/Cassowary.cs

@@ -3,13 +3,11 @@
 
 namespace Anvil.API
 {
-  //! ## Examples
-  //! @include CassowaryExamples.cs
-
   /// <summary>
   /// Represents a Cassowary engine structure.<br/>
   /// A Cassowary is a type of solver. NWN uses them internally to resize the newer GUI window.
   /// </summary>
+  /// <example>[!code-csharp[](~/../NWN.Anvil.Samples/src/main/API/EngineStructures/CassowaryExamples.cs)]</example>
   public sealed class Cassowary : EngineStructure
   {
     internal Cassowary(IntPtr handle, bool memoryOwn) : base(handle, memoryOwn) {}

NWN.Anvil/src/main/API/EngineStructures/Effect.cs

@@ -4,12 +4,10 @@
 
 namespace Anvil.API
 {
-  //! ## Examples
-  //! @include EffectExamples.cs
-
   /// <summary>
   /// Represents an effect engine structure.
   /// </summary>
+  /// <example>[!code-csharp[](~/../NWN.Anvil.Samples/src/main/API/EngineStructures/EffectExamples.cs)]</example>
   public sealed partial class Effect : EffectBase
   {
     internal Effect(CGameEffect effect, bool memoryOwn) : base(effect, memoryOwn) {}

NWN.Anvil/src/main/API/EngineStructures/ItemProperty.cs

@@ -5,12 +5,10 @@
 
 namespace Anvil.API
 {
-  //! ## Examples
-  //! @include ItemPropertyExamples.cs
-
   /// <summary>
   /// Represents an item property effect engine structure.
   /// </summary>
+  /// <example>[!code-csharp[](~/../NWN.Anvil.Samples/src/main/API/EngineStructures/ItemPropertyExamples.cs)]</example>
   public sealed partial class ItemProperty : EffectBase
   {
     internal ItemProperty(CGameEffect effect, bool memoryOwn) : base(effect, memoryOwn) {}

NWN.Anvil/src/main/API/Objects/NwCreature.cs

@@ -194,10 +194,11 @@ public int BaseAttackBonus
     /// <summary>
     /// Sets the number of base attacks for this creature.<br/>
     /// The range of values accepted are from 1 to 6.<br/>
-    /// @note Each successive attack per round suffers a -5 penalty.<br/>
+    /// </summary>
+    /// <remarks> Each successive attack per round suffers a -5 penalty.<br/>
     /// If the character has levels in Monk and fights with Unarmed Strike, each successive attack per round suffers a -3 penalty.<br/>
     /// These additional attacks are not shown on the player's character sheet.
-    /// </summary>
+    /// </remarks>
     public int BaseAttackCount
     {
       get => Creature.m_pStats.GetAttacksPerRound();

NWN.Anvil/src/main/API/Objects/NwGameObject.cs

@@ -429,7 +429,9 @@ public virtual void FaceToPoint(Vector3 point)
     /// <summary>
     /// Gets the color for the specified color channel.
     /// </summary>
-    /// @note A chart of available colors can be found here: https://nwnlexicon.com/index.php?title=Color_Charts
+    /// <remarks>
+    /// A chart of available colors can be found here: https://nwnlexicon.com/index.php?title=Color_Charts
+    /// </remarks>
     /// <param name="colorChannel">The color channel that you want to get the color value of.</param>
     /// <returns>The current color index value of the specified channel.</returns>
     public int GetColor(ColorChannel colorChannel)
@@ -544,8 +546,11 @@ public VisualTransform GetVisualTransform(ObjectVisualTransformDataScope scope)
 
     /// <summary>
     /// Gets whether this object has a direct line of sight to the specified object (not blocked by any geometry).<br/>
-    /// @note This is an expensive function and may degrade performance if used frequently.
     /// </summary>
+    /// <remarks>
+    /// &gt; [!WARNING]
+    /// &gt; This is an expensive function and may degrade performance if used frequently.
+    /// </remarks>
     /// <param name="target">The target object to perform the line of sight check against.</param>
     /// <returns>true if this object has line of sight on the target, otherwise false.</returns>
     public bool HasLineOfSight(NwGameObject target)
@@ -700,7 +705,9 @@ public SavingThrowResult RollSavingThrow(SavingThrow savingThrow, int dc, Saving
     /// <summary>
     /// Sets the color for the specified color channel.
     /// </summary>
-    /// @note A chart of available colors can be found here: https://nwnlexicon.com/index.php?title=Color_Charts
+    /// <remarks>
+    /// A chart of available colors can be found here: https://nwnlexicon.com/index.php?title=Color_Charts
+    /// </remarks>
     /// <param name="colorChannel">The color channel to modify.</param>
     /// <param name="newColor">The color channel's new color index.</param>
     public void SetColor(ColorChannel colorChannel, int newColor)

NWN.Anvil/src/main/API/Ruleset/NwFaction.cs

@@ -40,32 +40,47 @@ internal NwFaction(CNWSFaction faction)
 
     /// <summary>
     /// Gets the average Good/Evil alignment value of members in this faction.<br/>
-    /// @note This can be a costly operation when used on large NPC factions.
     /// </summary>
+    /// <remarks>
+    /// &gt; [!WARNING]
+    /// &gt; This can be a costly operation when used on large NPC factions.
+    /// </remarks>
     public int AverageGoodEvilAlignment => faction.GetAverageGoodEvilAlignment();
 
     /// <summary>
     /// Gets the average Law/Chaos alignment value of members in this faction.<br/>
-    /// @note This can be a costly operation when used on large NPC factions.
     /// </summary>
+    /// <remarks>
+    /// &gt; [!WARNING]
+    /// &gt; This can be a costly operation when used on large NPC factions.
+    /// </remarks>
     public int AverageLawChaosAlignment => faction.GetAverageLawChaosAlignment();
 
     /// <summary>
     /// Gets the average level of members in this faction.<br/>
-    /// @note This can be a costly operation when used on large NPC factions.
     /// </summary>
+    /// <remarks>
+    /// &gt; [!WARNING]
+    /// &gt; This can be a costly operation when used on large NPC factions.
+    /// </remarks>
     public int AverageLevel => faction.GetAverageLevel();
 
     /// <summary>
     /// Gets the average amount of XP of members in this faction.<br/>
-    /// @note This can be a costly operation when used on large NPC factions.
     /// </summary>
+    /// <remarks>
+    /// &gt; [!WARNING]
+    /// &gt; This can be a costly operation when used on large NPC factions.
+    /// </remarks>
     public int AverageXP => faction.GetAverageXP();
 
     /// <summary>
     /// Gets the total amount of gold held by all members of this party.<br/>
-    /// @note This can be a costly operation when used on large NPC factions.
     /// </summary>
+    /// <remarks>
+    /// &gt; [!WARNING]
+    /// &gt; This can be a costly operation when used on large NPC factions.
+    /// </remarks>
     public int Gold => faction.GetGold();
 
     /// <summary>
@@ -80,8 +95,11 @@ internal NwFaction(CNWSFaction faction)
 
     /// <summary>
     /// Gets the most common type of class among the members of this faction/party.<br/>
-    /// @note This can be a costly operation when used on large NPC factions.
     /// </summary>
+    /// <remarks>
+    /// &gt; [!WARNING]
+    /// &gt; This can be a costly operation when used on large NPC factions.
+    /// </remarks>
     public NwClass MostFrequentClass => NwClass.FromClassId(faction.GetMostFrequentClass())!;
 
     /// <summary>
@@ -196,8 +214,11 @@ public NwCreature GetLeastDamagedMember(NwCreature? referenceCreature = null, bo
 
     /// <summary>
     /// Gets all creatures that are members of this faction.<br/>
-    /// @note This can be a very costly operation when used on large NPC factions.
     /// </summary>
+    /// <remarks>
+    /// &gt; [!WARNING]
+    /// &gt; This can be a costly operation when used on large NPC factions.
+    /// </remarks>
     /// <returns>All creatures in this faction.</returns>
     public List<NwCreature> GetMembers()
     {

NWN.Anvil/src/main/API/Ruleset/NwRuleset.cs

@@ -49,8 +49,11 @@ public static class NwRuleset
 
     /// <summary>
     /// Reloads all game rules (2da stuff, etc).<br/>
-    /// @warning DANGER, DRAGONS. Bad things may or may not happen. Only use this if you know what you are doing.
     /// </summary>
+    /// <remarks>
+    /// &gt; [!WARNING]
+    /// &gt; DANGER, DRAGONS. Bad things may or may not happen. Only use this if you know what you are doing.
+    /// </remarks>
     public static void ReloadRules()
     {
       NWNXLib.Rules().ReloadAll();