From 59d3b46b063de87bad4e5b49ca3999d7b7dbc835 Mon Sep 17 00:00:00 2001
From: Christopher Whitley <103014489+AristurtleDev@users.noreply.github.com>
Date: Tue, 2 Sep 2025 12:20:04 -0400
Subject: [PATCH 1/7] Use dll assemblies for documentation reference instead of
 having docfx attempt to build projects

---
 docfx.json | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docfx.json b/docfx.json
index 1fc4b077..36d1fa7d 100644
--- a/docfx.json
+++ b/docfx.json
@@ -4,8 +4,8 @@
       "src": [
         {
           "files": [
-            "external/MonoGame/MonoGame.Framework/MonoGame.Framework.DesktopGL.csproj",
-            "external/MonoGame/MonoGame.Framework.Content.Pipeline/MonoGame.Framework.Content.Pipeline.csproj"
+            "external/MonoGame/Artifacts/MonoGame.Framework/DesktopGL/Debug/MonoGame.Framework.dll",
+            "external/MonoGame/Artifacts/MonoGame.Framework.Content.Pipeline/Debug/MonoGame.Framework.Content.Pipeline.dll"
           ]
         }
       ],

From 2c9f0c8a64966b4146bb0b2901a5d82319d22831 Mon Sep 17 00:00:00 2001
From: Christopher Whitley <103014489+AristurtleDev@users.noreply.github.com>
Date: Tue, 2 Sep 2025 12:21:14 -0400
Subject: [PATCH 2/7] Added bash and powershell scripts to build perform
 documentation build

---
 build.ps1 |  9 +++++++++
 build.sh  | 11 +++++++++++
 2 files changed, 20 insertions(+)
 create mode 100644 build.ps1
 create mode 100644 build.sh

diff --git a/build.ps1 b/build.ps1
new file mode 100644
index 00000000..7d6efedd
--- /dev/null
+++ b/build.ps1
@@ -0,0 +1,9 @@
+$ErrorActionPreference = "Stop"
+
+Write-Host "Building MonoGame Assemblies..."-ForegroundColor Green
+dotnet build external/MonoGame/MonoGame.Framework.Content.Pipeline/MonoGame.Framework.Content.Pipeline.csproj -p:DisableNativeBuild=true
+
+Write-Host "Running DocFX..." -ForegroundColor Green
+dotnet docfx docfx.json
+
+Write-Host "Build and documentation generation completed successfully!" -ForegroundColor Green
\ No newline at end of file
diff --git a/build.sh b/build.sh
new file mode 100644
index 00000000..12e11ce1
--- /dev/null
+++ b/build.sh
@@ -0,0 +1,11 @@
+#!/bin/bash
+
+set -e
+
+echo "Building MonoGame Assemblies..."
+dotnet build external/MonoGame/MonoGame.Framework.Content.Pipeline/MonoGame.Framework.Content.Pipeline.csproj -p:DisableNativeBuild=true
+
+echo "Running DocFX..."
+dotnet docfx docfx.json
+
+echo "Build and documentation generation completed successfully!"
\ No newline at end of file

From bbcbd8206ec156d8a21470ad7963a9d63792e4cb Mon Sep 17 00:00:00 2001
From: Christopher Whitley <103014489+AristurtleDev@users.noreply.github.com>
Date: Tue, 2 Sep 2025 12:24:33 -0400
Subject: [PATCH 3/7] Update workflows to use bash script for build

---
 .github/workflows/main.yml        | 4 +++-
 .github/workflows/pullrequest.yml | 4 +++-
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index 5615d1a4..521d0022 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -43,7 +43,9 @@ jobs:
         run: dotnet tool restore
 
       - name: Run Build
-        run: dotnet docfx docfx.json
+        run: |
+          chmod +x ./build.sh
+          ./build.sh
 
       - name: Setup Pages
         uses: actions/configure-pages@v5
diff --git a/.github/workflows/pullrequest.yml b/.github/workflows/pullrequest.yml
index 4319ec03..08aa6443 100644
--- a/.github/workflows/pullrequest.yml
+++ b/.github/workflows/pullrequest.yml
@@ -43,7 +43,9 @@ jobs:
         run: dotnet tool restore
 
       - name: Run Build
-        run: dotnet docfx docfx.json
+        run: |
+          chmod +x ./build.sh
+          ./build.sh        
 
   complete:
     runs-on: ubuntu-latest

From 9f21e60c134fcb58efd5e97c332d5fa91c476d3a Mon Sep 17 00:00:00 2001
From: Christopher Whitley <103014489+AristurtleDev@users.noreply.github.com>
Date: Tue, 2 Sep 2025 13:13:14 -0400
Subject: [PATCH 4/7] Initialize submodules and build only if needed

---
 build.ps1 | 21 ++++++++++++++++++---
 build.sh  | 19 ++++++++++++++++---
 2 files changed, 34 insertions(+), 6 deletions(-)

diff --git a/build.ps1 b/build.ps1
index 7d6efedd..3443d72b 100644
--- a/build.ps1
+++ b/build.ps1
@@ -1,9 +1,24 @@
+# Exit on any error
 $ErrorActionPreference = "Stop"
 
-Write-Host "Building MonoGame Assemblies..."-ForegroundColor Green
-dotnet build external/MonoGame/MonoGame.Framework.Content.Pipeline/MonoGame.Framework.Content.Pipeline.csproj -p:DisableNativeBuild=true
+$FrameworkDll = "external/MonoGame/Artifacts/MonoGame.Framework/DesktopGL/Debug/MonoGame.Framework.dll"
+$PipelineDll = "external/MonoGame/Artifacts/MonoGame.Framework.Content.Pipeline/Debug/MonoGame.Framework.Content.Pipeline.dll"
 
-Write-Host "Running DocFX..." -ForegroundColor Green
+# Check if submodules are initialized
+$submoduleStatus = git submodule status
+if ($submoduleStatus -match '^-') {
+    Write-Host "Submodules not initialized. Running git submodule update..." -ForegroundColor Yellow
+    git submodule update --init --recursive
+}
+
+# Check if dlls are already built
+if (-not (Test-Path $FrameworkDll) -or -not (Test-Path $PipelineDll)) {
+    Write-Host "Required Assemblies for documentation not found. Building assemblies..." -ForegroundColor Yellow
+    dotnet build external/MonoGame/MonoGame.Framework.Content.Pipeline/MonoGame.Framework.Content.Pipeline.csproj -p:DisableNativeBuild=true
+}
+
+# Build documentation
+Write-Host "Building DocFx..." -ForegroundColor Green
 dotnet docfx docfx.json
 
 Write-Host "Build and documentation generation completed successfully!" -ForegroundColor Green
\ No newline at end of file
diff --git a/build.sh b/build.sh
index 12e11ce1..210206b2 100644
--- a/build.sh
+++ b/build.sh
@@ -2,10 +2,23 @@
 
 set -e
 
-echo "Building MonoGame Assemblies..."
-dotnet build external/MonoGame/MonoGame.Framework.Content.Pipeline/MonoGame.Framework.Content.Pipeline.csproj -p:DisableNativeBuild=true
+FRAMEWORK_DLL="external/MonoGame/Artifacts/MonoGame.Framework/DesktopGL/Debug/MonoGame.Framework.dll"
+PIPELINE_DLL="external/MonoGame/Artifacts/MonoGame.Framework.Content.Pipeline/Debug/MonoGame.Framework.Content.Pipeline.dll"
 
-echo "Running DocFX..."
+# Check if submodules are initialized
+if git submodule status | grep -q '^-'; then
+    echo "Submodules not initialized.  Running git submodule update..."
+    git submodule update --init --recursive
+fi
+
+# Check if dlls are already built
+if [ ! -f "$FRAMEWORK_DLL" ] || [ ! -f "$PIPELINE_DLL" ]; then
+    echo "Required Assemblies for documentation not found.  Building assemblies..."
+    dotnet build external/MonoGame/MonoGame.Framework.Content.Pipeline/MonoGame.Framework.Content.Pipeline.csproj -p:DisableNativeBuild=true
+fi
+
+# Build documentation
+echo "Building DocFx..."
 dotnet docfx docfx.json
 
 echo "Build and documentation generation completed successfully!"
\ No newline at end of file

From 1550de9e4453bfcc28ee2eb1eda4e70af11459d3 Mon Sep 17 00:00:00 2001
From: Christopher Whitley <103014489+AristurtleDev@users.noreply.github.com>
Date: Tue, 2 Sep 2025 13:13:25 -0400
Subject: [PATCH 5/7] Add serve script

---
 serve.ps1 | 8 ++++++++
 serve.sh  | 9 +++++++++
 2 files changed, 17 insertions(+)
 create mode 100644 serve.ps1
 create mode 100644 serve.sh

diff --git a/serve.ps1 b/serve.ps1
new file mode 100644
index 00000000..589eebe6
--- /dev/null
+++ b/serve.ps1
@@ -0,0 +1,8 @@
+# Exit on any error
+$ErrorActionPreference = "Stop"
+
+# Run the build script to make sure there's something to serve
+.\build.ps1
+
+# Start DocFx serve
+dotnet docfx docfx.json --serve
\ No newline at end of file
diff --git a/serve.sh b/serve.sh
new file mode 100644
index 00000000..ce05a254
--- /dev/null
+++ b/serve.sh
@@ -0,0 +1,9 @@
+#!/bin/bash
+
+set -e
+
+# Run the build script to make sure there's something to serve
+./build.sh
+
+# Start DocFx serve
+dotnet docfx docfx.json --serve
\ No newline at end of file

From 3af795bbdbc66411a13db3d2cbed262a52ab2f66 Mon Sep 17 00:00:00 2001
From: Christopher Whitley <103014489+AristurtleDev@users.noreply.github.com>
Date: Tue, 2 Sep 2025 13:15:28 -0400
Subject: [PATCH 6/7] Update readme

---
 README.md | 46 +++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 41 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index fa5ef927..67a9b54c 100644
--- a/README.md
+++ b/README.md
@@ -22,15 +22,51 @@ With your environment setup properly, the following explains how to build from s
     dotnet tool restore
     ```
 
-3. Optional Steps
+3. Build and serve the documentation
 
-   If you want to generate the API Reference documentation locally, you will need to ensure that the MonoGame submodule has been initialized by running
+   The easiest way to build and serve the documentation locally is using the provided scripts:
 
-   `git submodule update --init --recursive`
+   **On Windows (PowerShell):**
 
-4. Run a local build and serve it. The site is full DocFX now so a single build command will do:
+   ```powershell
+   .\serve.ps1
+   ```
 
-  `dotnet docfx docfx.json --serve`
+   **On macOS/Linux (Bash):**
+
+   ```bash
+   ./serve.sh
+   ```
+
+   These scripts will automatically:
+   - Initialize MonoGame submodules if needed
+   - Build required assemblies for API documentation
+   - Generate the complete documentation
+   - Start a local web server
+
+4. Alternative: Build-only (without serving)
+
+   If you only want to build the documentation without serving:
+
+   **On Windows (PowerShell):**
+
+   ```powershell
+   .\build.ps1
+   ```
+
+   **On macOS/Linux (Bash):**
+
+   ```bash
+   ./build.sh
+   ```
+
+   **Or manually using DocFX:**
+
+   ```sh
+   dotnet docfx docfx.json
+
+> [!NOTE]
+> The build scripts automatically handle submodule initialization and MonoGame assembly building. They only perform these steps when necessary, making subsequent builds faster.
 
 > [!NOTE]
 > Docfx hosting does not support hot reload, so to refresh the hosted site you will need to run `docfx docfx.json` in a separate terminal or stop and rerun the agent (ctrl-c)

From f5d54c777d3738ea92c9f7a929b39b9da5ac1f43 Mon Sep 17 00:00:00 2001
From: Christopher Whitley <103014489+AristurtleDev@users.noreply.github.com>
Date: Tue, 2 Sep 2025 13:26:40 -0400
Subject: [PATCH 7/7] Use projects for CI builds

---
 .github/workflows/main.yml        |  4 +-
 .github/workflows/pullrequest.yml |  4 +-
 ci.docfx.json                     | 95 +++++++++++++++++++++++++++++++
 3 files changed, 97 insertions(+), 6 deletions(-)
 create mode 100644 ci.docfx.json

diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index 521d0022..1516cc42 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -43,9 +43,7 @@ jobs:
         run: dotnet tool restore
 
       - name: Run Build
-        run: |
-          chmod +x ./build.sh
-          ./build.sh
+        run: dotnet docfx ci.docfx.json
 
       - name: Setup Pages
         uses: actions/configure-pages@v5
diff --git a/.github/workflows/pullrequest.yml b/.github/workflows/pullrequest.yml
index 08aa6443..4170c87f 100644
--- a/.github/workflows/pullrequest.yml
+++ b/.github/workflows/pullrequest.yml
@@ -43,9 +43,7 @@ jobs:
         run: dotnet tool restore
 
       - name: Run Build
-        run: |
-          chmod +x ./build.sh
-          ./build.sh        
+        run: dotnet docfx ci.docfx.json
 
   complete:
     runs-on: ubuntu-latest
diff --git a/ci.docfx.json b/ci.docfx.json
new file mode 100644
index 00000000..1fc4b077
--- /dev/null
+++ b/ci.docfx.json
@@ -0,0 +1,95 @@
+{
+  "metadata": [
+    {
+      "src": [
+        {
+          "files": [
+            "external/MonoGame/MonoGame.Framework/MonoGame.Framework.DesktopGL.csproj",
+            "external/MonoGame/MonoGame.Framework.Content.Pipeline/MonoGame.Framework.Content.Pipeline.csproj"
+          ]
+        }
+      ],
+      "dest": "api",
+      "includePrivateMembers": false,
+      "disableGitFeatures": false,
+      "disableDefaultFilter": false,
+      "noRestore": false,
+      "namespaceLayout": "flattened",
+      "memberLayout": "samePage",
+      "EnumSortOrder": "alphabetic"
+    }
+  ],
+  "rules": {
+    "InvalidFileLink": "error",
+    "InvalidBookmark": "error",
+    "UidNotFound": "error",
+    "ReferencedXrefPropertyNotString": "error"
+  },  
+  "build": {
+    "content": [
+      {
+        "files": [
+          "api/**/*.yml",
+          "api/**/*.md"
+        ]
+      },
+      {
+        "files": [
+          "articles/**/*.md",
+          "articles/**/*.yml",
+          "foundation/**/*.md",
+          "roadmap/**/*.md",
+          "roadmap/**/*.yml",
+          "errors/**/*.md",
+          "toc.yml",
+          "*.md"
+        ],
+        "exclude": [ "_site/**", "README.md" ]
+      }
+    ],
+    "resource": [
+      {
+        "files": [
+          "**/images/**",
+          "**/videos/**",
+          "**/files/**",
+          "**/snippets/**",
+          "CNAME"
+        ]
+      }
+    ],
+    "output": "_site",
+    "globalMetadata": {
+      "_appLogoUrl": "https://monogame.net",
+      "_appFaviconPath": "/images/favicon.png",
+      "_disableBreadcrumb": "true",
+      "_appFooter": "Copyright © 2009-2025 MonoGame Foundation, Inc.",
+      "_hostname": "monogame.net",
+      "_openGraphImage": "images/social_embed_image.png",
+      "_description": "One framework for creating powerful cross-platform games.",
+      "_appTitle": "MonoGame",
+      "_enableSearch": true
+    },
+    "template": [
+      "default",
+      "modern",
+      "templates/monogame"
+    ],
+    "markdownEngineProperties": {
+      "markdigExtensions": [
+        "Abbreviations",
+        "Figures",
+        "CustomContainers",
+        "attributes"
+      ]
+    },
+    "postProcessors": [],
+    "keepFileLink": false,
+    "disableGitFeatures": false,
+    "sitemap": {
+      "baseUrl": "https://docs.monogame.net/",
+      "priority": 0.1,
+      "changefreq": "monthly"
+    }    
+  }
+}
\ No newline at end of file