Prebuild Assemblies And Reference Them For Documentation Builds

.github/workflows/main.yml

@@ -43,7 +43,7 @@ jobs:
         run: dotnet tool restore
 
       - name: Run Build
-        run: dotnet docfx docfx.json
+        run: dotnet docfx ci.docfx.json
 
       - name: Setup Pages
         uses: actions/configure-pages@v5

.github/workflows/pullrequest.yml

@@ -43,7 +43,7 @@ jobs:
         run: dotnet tool restore
 
       - name: Run Build
-        run: dotnet docfx docfx.json
+        run: dotnet docfx ci.docfx.json
 
   complete:
     runs-on: ubuntu-latest

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)

build.ps1

@@ -0,0 +1,24 @@
+# Exit on any error
+$ErrorActionPreference = "Stop"
+
+$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"
+
+# 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

build.sh

@@ -0,0 +1,24 @@
+#!/bin/bash
+
+set -e
+
+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"
+
+# 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!"

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"
+    }    
+  }
+}

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"
           ]
         }
       ],

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

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