chore: migrate to docfx (#43)

* chore: files changed randomly

* feat: add initial docfx settings

* test: first test of docfx in pipeline

* test: run pipeline

* test: run pipeline

* fix: set correct pipeline trigger

* fix: set correct github pages uploading

* test: change pages and remove contribution

* test: see how docs work in docfx

* fix: fix docs

* chore: add embedded quick start guide

* chore: remove docs; reference to github wiki is sufficient

* fix: remove Docs folder reference

* fix: re-instate some docs (with just a reference)

* fix: set disable contribution flag correctly

* chore: improve homepage

* fix: set correct API page link

* fix: set correct API page link

* chore: remove pr run pipeline

---------

Co-authored-by: Quake <QuakeEye@users.noreply.GitHub.com>

.github/workflows/build-documentation.yml

@@ -1,40 +1,41 @@
-name: Build Doxygen
+name: Build Docfx Documentation
 
 on:
   push:
     branches:
       - main
 
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  actions: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
 jobs:
-  build-doxygen:
-    name: Build Doxygen
+  build-docfx:
+    name: Build Docfx
     runs-on: ubuntu-latest
     permissions: write-all
     steps:
       - name: Checkout the repository
         uses: actions/checkout@v4
         with:
           submodules: true
-      - name: Install Doxygen
-        run: |
-          sudo apt-get install -y graphviz
-          mkdir doxygen-install
-          cd doxygen-install
-          wget https://www.doxygen.nl/files/doxygen-1.10.0.linux.bin.tar.gz
-          tar -xvf doxygen-1.10.0.linux.bin.tar.gz
-          sudo mv doxygen-1.10.0/bin/doxygen /usr/bin/doxygen
-          cd ..
-          sudo rm -rf doxygen-install
-        shell: bash
-      - name: Generate Doxygen Documentation
-        run: /usr/bin/doxygen Doxygen/Doxyfile
-        shell: bash
-      - name: Create .nojekyll (ensures pages with underscores work on gh pages)
-        run: touch Doxygen/.nojekyll
-        shell: bash
-      - name: Upload Doxygen Documentation to Github Pages
-        uses: peaceiris/actions-gh-pages@v3
+      - name: Dotnet Setup
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: 8.x
+      - run: dotnet tool update -g docfx
+      - run: docfx docfx.json
+      - name: Upload Docfx Documentation to Github Pages
+        uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_branch: gh-pages
-          publish_dir: Doxygen/Generated/html
+          publish_dir: _site

Aplib.Core/Desire/FirstOfGoalStructure.cs

@@ -1,80 +1,80 @@
-using Aplib.Core.Belief;
-using Aplib.Core.Desire.Goals;
-using System;
-using System.Collections.Generic;
-
-namespace Aplib.Core.Desire
-{
-    /// <summary>
-    /// Represents a goal structure that will complete if any of its children complete.
-    /// </summary>
-    /// <remarks>
-    /// The children of this goal structure will be executed in the order they are given.
-    /// </remarks>
-    /// <typeparam name="TBeliefSet">The beliefset of the agent.</typeparam>
-    public class FirstOfGoalStructure<TBeliefSet> : GoalStructure<TBeliefSet>, IDisposable
-        where TBeliefSet : IBeliefSet
-    {
-        private IEnumerator<IGoalStructure<TBeliefSet>> _childrenEnumerator { get; }
-
-        /// <summary>
-        /// Initializes a new instance of the <see cref="FirstOfGoalStructure{TBeliefSet}" /> class.
-        /// </summary>
-        /// <param name="children">The children of the goal structure.</param>
-        public FirstOfGoalStructure(params IGoalStructure<TBeliefSet>[] children) : base(children)
-        {
-            _childrenEnumerator = _children.GetEnumerator();
-            _childrenEnumerator.MoveNext();
-            _currentGoalStructure = _childrenEnumerator.Current;
-        }
-
-        /// <inheritdoc />
-        public override IGoal<TBeliefSet> GetCurrentGoal(TBeliefSet beliefSet) => _currentGoalStructure!.GetCurrentGoal(beliefSet);
-
-        /// <inheritdoc />
-        public override void UpdateStatus(TBeliefSet beliefSet)
-        {
-            // Loop through all the children until one of them is unfinished or successful.
-            // This loop is here to prevent tail recursion.
-            while (true)
-            {
-                if (Status == CompletionStatus.Success) return;
-                _currentGoalStructure!.UpdateStatus(beliefSet);
-
-                switch (_currentGoalStructure.Status)
-                {
-                    case CompletionStatus.Unfinished:
-                        return;
-                    case CompletionStatus.Success:
-                        Status = CompletionStatus.Success;
-                        return;
-                }
-
-                if (_childrenEnumerator.MoveNext())
-                {
-                    _currentGoalStructure = _childrenEnumerator.Current;
-                    Status = CompletionStatus.Unfinished;
-
-                    // Update the Status of the new goal structure
-                    continue;
-                }
-
-                Status = CompletionStatus.Failure;
-                return;
-            }
-        }
-
-        /// <inheritdoc />
-        public void Dispose()
-        {
-            Dispose(true);
-            GC.SuppressFinalize(this);
-        }
-
-        /// <summary>
-        /// Disposes of the goal structure.
-        /// </summary>
-        /// <param name="disposing">Whether we are actually disposing.</param>
-        protected virtual void Dispose(bool disposing) => _childrenEnumerator.Dispose();
-    }
-}
+using Aplib.Core.Belief;
+using Aplib.Core.Desire.Goals;
+using System;
+using System.Collections.Generic;
+
+namespace Aplib.Core.Desire
+{
+    /// <summary>
+    /// Represents a goal structure that will complete if any of its children complete.
+    /// </summary>
+    /// <remarks>
+    /// The children of this goal structure will be executed in the order they are given.
+    /// </remarks>
+    /// <typeparam name="TBeliefSet">The beliefset of the agent.</typeparam>
+    public class FirstOfGoalStructure<TBeliefSet> : GoalStructure<TBeliefSet>, IDisposable
+        where TBeliefSet : IBeliefSet
+    {
+        private IEnumerator<IGoalStructure<TBeliefSet>> _childrenEnumerator { get; }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="FirstOfGoalStructure{TBeliefSet}" /> class.
+        /// </summary>
+        /// <param name="children">The children of the goal structure.</param>
+        public FirstOfGoalStructure(params IGoalStructure<TBeliefSet>[] children) : base(children)
+        {
+            _childrenEnumerator = _children.GetEnumerator();
+            _childrenEnumerator.MoveNext();
+            _currentGoalStructure = _childrenEnumerator.Current;
+        }
+
+        /// <inheritdoc />
+        public override IGoal<TBeliefSet> GetCurrentGoal(TBeliefSet beliefSet) => _currentGoalStructure!.GetCurrentGoal(beliefSet);
+
+        /// <inheritdoc />
+        public override void UpdateStatus(TBeliefSet beliefSet)
+        {
+            // Loop through all the children until one of them is unfinished or successful.
+            // This loop is here to prevent tail recursion.
+            while (true)
+            {
+                if (Status == CompletionStatus.Success) return;
+                _currentGoalStructure!.UpdateStatus(beliefSet);
+
+                switch (_currentGoalStructure.Status)
+                {
+                    case CompletionStatus.Unfinished:
+                        return;
+                    case CompletionStatus.Success:
+                        Status = CompletionStatus.Success;
+                        return;
+                }
+
+                if (_childrenEnumerator.MoveNext())
+                {
+                    _currentGoalStructure = _childrenEnumerator.Current;
+                    Status = CompletionStatus.Unfinished;
+
+                    // Update the Status of the new goal structure
+                    continue;
+                }
+
+                Status = CompletionStatus.Failure;
+                return;
+            }
+        }
+
+        /// <inheritdoc />
+        public void Dispose()
+        {
+            Dispose(true);
+            GC.SuppressFinalize(this);
+        }
+
+        /// <summary>
+        /// Disposes of the goal structure.
+        /// </summary>
+        /// <param name="disposing">Whether we are actually disposing.</param>
+        protected virtual void Dispose(bool disposing) => _childrenEnumerator.Dispose();
+    }
+}

Aplib.Core/Desire/GoalStructure.cs

@@ -1,45 +1,45 @@
-using Aplib.Core.Belief;
-using Aplib.Core.Desire.Goals;
-using System.Collections.Generic;
-
-namespace Aplib.Core.Desire
-{
-    /// <summary>
-    /// Describes a structure of goals that need to be fulfilled.
-    /// </summary>
-    public abstract class GoalStructure<TBeliefSet> : IGoalStructure<TBeliefSet>
-        where TBeliefSet : IBeliefSet
-    {
-        /// <inheritdoc />
-        public CompletionStatus Status { get; protected set; }
-
-        /// <summary>
-        /// The children of the goal structure.
-        /// </summary>
-        protected readonly IEnumerable<IGoalStructure<TBeliefSet>> _children;
-
-        /// <summary>
-        /// The goal structure that is currently being fulfilled.
-        /// </summary>
-        protected IGoalStructure<TBeliefSet>? _currentGoalStructure;
-
-        /// <summary>
-        /// Initializes a new instance of the <see cref="GoalStructure{TBeliefSet}" /> class.
-        /// </summary>
-        /// <param name="children">The children of the goal structure.</param>
-        protected GoalStructure(IEnumerable<IGoalStructure<TBeliefSet>> children) => _children = children;
-
-        /// <summary>
-        /// Gets the current goal using the given <see cref="IBeliefSet" />.
-        /// </summary>
-        /// <param name="beliefSet">The belief set of the agent.</param>
-        /// <returns>The current goal to be fulfilled.</returns>
-        public abstract IGoal<TBeliefSet> GetCurrentGoal(TBeliefSet beliefSet);
-
-        /// <summary>
-        /// Updates the state of the goal structure.
-        /// </summary>
-        /// <param name="beliefSet">The belief set of the agent.</param>
-        public abstract void UpdateStatus(TBeliefSet beliefSet);
-    }
-}
+using Aplib.Core.Belief;
+using Aplib.Core.Desire.Goals;
+using System.Collections.Generic;
+
+namespace Aplib.Core.Desire
+{
+    /// <summary>
+    /// Describes a structure of goals that need to be fulfilled.
+    /// </summary>
+    public abstract class GoalStructure<TBeliefSet> : IGoalStructure<TBeliefSet>
+        where TBeliefSet : IBeliefSet
+    {
+        /// <inheritdoc />
+        public CompletionStatus Status { get; protected set; }
+
+        /// <summary>
+        /// The children of the goal structure.
+        /// </summary>
+        protected readonly IEnumerable<IGoalStructure<TBeliefSet>> _children;
+
+        /// <summary>
+        /// The goal structure that is currently being fulfilled.
+        /// </summary>
+        protected IGoalStructure<TBeliefSet>? _currentGoalStructure;
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="GoalStructure{TBeliefSet}" /> class.
+        /// </summary>
+        /// <param name="children">The children of the goal structure.</param>
+        protected GoalStructure(IEnumerable<IGoalStructure<TBeliefSet>> children) => _children = children;
+
+        /// <summary>
+        /// Gets the current goal using the given <see cref="IBeliefSet" />.
+        /// </summary>
+        /// <param name="beliefSet">The belief set of the agent.</param>
+        /// <returns>The current goal to be fulfilled.</returns>
+        public abstract IGoal<TBeliefSet> GetCurrentGoal(TBeliefSet beliefSet);
+
+        /// <summary>
+        /// Updates the state of the goal structure.
+        /// </summary>
+        /// <param name="beliefSet">The belief set of the agent.</param>
+        public abstract void UpdateStatus(TBeliefSet beliefSet);
+    }
+}