Skip to content

Commit a00bd43

Browse files
AristurtleDevAristurtleDev
authored
Prebuild Assemblies And Reference Them For Documentation Builds (#175)
* Use dll assemblies for documentation reference instead of having docfx attempt to build projects * Added bash and powershell scripts to build perform documentation build * Update workflows to use bash script for build * Initialize submodules and build only if needed * Add serve script * Update readme * Use projects for CI builds
1 parent fad20a5 commit a00bd43

File tree

9 files changed

+205
-9
lines changed

9 files changed

+205
-9
lines changed

‎.github/workflows/main.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ jobs:
4343
run: dotnet tool restore
4444

4545
- name: Run Build
46-
run: dotnet docfx docfx.json
46+
run: dotnet docfx ci.docfx.json
4747

4848
- name: Setup Pages
4949
uses: actions/configure-pages@v5

‎.github/workflows/pullrequest.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ jobs:
4343
run: dotnet tool restore
4444

4545
- name: Run Build
46-
run: dotnet docfx docfx.json
46+
run: dotnet docfx ci.docfx.json
4747

4848
complete:
4949
runs-on: ubuntu-latest

‎README.md‎

Lines changed: 41 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -22,15 +22,51 @@ With your environment setup properly, the following explains how to build from s
2222
dotnet tool restore
2323
```
2424

25-
3. Optional Steps
25+
3. Build and serve the documentation
2626

27-
If you want to generate the API Reference documentation locally, you will need to ensure that the MonoGame submodule has been initialized by running
27+
The easiest way to build and serve the documentation locally is using the provided scripts:
2828

29-
`git submodule update --init --recursive`
29+
**On Windows (PowerShell):**
3030

31-
4. Run a local build and serve it. The site is full DocFX now so a single build command will do:
31+
```powershell
32+
.\serve.ps1
33+
```
3234

33-
`dotnet docfx docfx.json --serve`
35+
**On macOS/Linux (Bash):**
36+
37+
```bash
38+
./serve.sh
39+
```
40+
41+
These scripts will automatically:
42+
- Initialize MonoGame submodules if needed
43+
- Build required assemblies for API documentation
44+
- Generate the complete documentation
45+
- Start a local web server
46+
47+
4. Alternative: Build-only (without serving)
48+
49+
If you only want to build the documentation without serving:
50+
51+
**On Windows (PowerShell):**
52+
53+
```powershell
54+
.\build.ps1
55+
```
56+
57+
**On macOS/Linux (Bash):**
58+
59+
```bash
60+
./build.sh
61+
```
62+
63+
**Or manually using DocFX:**
64+
65+
```sh
66+
dotnet docfx docfx.json
67+
68+
> [!NOTE]
69+
> The build scripts automatically handle submodule initialization and MonoGame assembly building. They only perform these steps when necessary, making subsequent builds faster.
3470
3571
> [!NOTE]
3672
> 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‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Exit on any error
2+
$ErrorActionPreference = "Stop"
3+
4+
$FrameworkDll = "external/MonoGame/Artifacts/MonoGame.Framework/DesktopGL/Debug/MonoGame.Framework.dll"
5+
$PipelineDll = "external/MonoGame/Artifacts/MonoGame.Framework.Content.Pipeline/Debug/MonoGame.Framework.Content.Pipeline.dll"
6+
7+
# Check if submodules are initialized
8+
$submoduleStatus = git submodule status
9+
if ($submoduleStatus -match '^-') {
10+
Write-Host "Submodules not initialized. Running git submodule update..." -ForegroundColor Yellow
11+
git submodule update --init --recursive
12+
}
13+
14+
# Check if dlls are already built
15+
if (-not (Test-Path $FrameworkDll) -or -not (Test-Path $PipelineDll)) {
16+
Write-Host "Required Assemblies for documentation not found. Building assemblies..." -ForegroundColor Yellow
17+
dotnet build external/MonoGame/MonoGame.Framework.Content.Pipeline/MonoGame.Framework.Content.Pipeline.csproj -p:DisableNativeBuild=true
18+
}
19+
20+
# Build documentation
21+
Write-Host "Building DocFx..." -ForegroundColor Green
22+
dotnet docfx docfx.json
23+
24+
Write-Host "Build and documentation generation completed successfully!" -ForegroundColor Green

‎build.sh‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
#!/bin/bash
2+
3+
set -e
4+
5+
FRAMEWORK_DLL="external/MonoGame/Artifacts/MonoGame.Framework/DesktopGL/Debug/MonoGame.Framework.dll"
6+
PIPELINE_DLL="external/MonoGame/Artifacts/MonoGame.Framework.Content.Pipeline/Debug/MonoGame.Framework.Content.Pipeline.dll"
7+
8+
# Check if submodules are initialized
9+
if git submodule status | grep -q '^-'; then
10+
echo "Submodules not initialized. Running git submodule update..."
11+
git submodule update --init --recursive
12+
fi
13+
14+
# Check if dlls are already built
15+
if [ ! -f "$FRAMEWORK_DLL" ] || [ ! -f "$PIPELINE_DLL" ]; then
16+
echo "Required Assemblies for documentation not found. Building assemblies..."
17+
dotnet build external/MonoGame/MonoGame.Framework.Content.Pipeline/MonoGame.Framework.Content.Pipeline.csproj -p:DisableNativeBuild=true
18+
fi
19+
20+
# Build documentation
21+
echo "Building DocFx..."
22+
dotnet docfx docfx.json
23+
24+
echo "Build and documentation generation completed successfully!"

‎ci.docfx.json‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
{
2+
"metadata": [
3+
{
4+
"src": [
5+
{
6+
"files": [
7+
"external/MonoGame/MonoGame.Framework/MonoGame.Framework.DesktopGL.csproj",
8+
"external/MonoGame/MonoGame.Framework.Content.Pipeline/MonoGame.Framework.Content.Pipeline.csproj"
9+
]
10+
}
11+
],
12+
"dest": "api",
13+
"includePrivateMembers": false,
14+
"disableGitFeatures": false,
15+
"disableDefaultFilter": false,
16+
"noRestore": false,
17+
"namespaceLayout": "flattened",
18+
"memberLayout": "samePage",
19+
"EnumSortOrder": "alphabetic"
20+
}
21+
],
22+
"rules": {
23+
"InvalidFileLink": "error",
24+
"InvalidBookmark": "error",
25+
"UidNotFound": "error",
26+
"ReferencedXrefPropertyNotString": "error"
27+
},
28+
"build": {
29+
"content": [
30+
{
31+
"files": [
32+
"api/**/*.yml",
33+
"api/**/*.md"
34+
]
35+
},
36+
{
37+
"files": [
38+
"articles/**/*.md",
39+
"articles/**/*.yml",
40+
"foundation/**/*.md",
41+
"roadmap/**/*.md",
42+
"roadmap/**/*.yml",
43+
"errors/**/*.md",
44+
"toc.yml",
45+
"*.md"
46+
],
47+
"exclude": [ "_site/**", "README.md" ]
48+
}
49+
],
50+
"resource": [
51+
{
52+
"files": [
53+
"**/images/**",
54+
"**/videos/**",
55+
"**/files/**",
56+
"**/snippets/**",
57+
"CNAME"
58+
]
59+
}
60+
],
61+
"output": "_site",
62+
"globalMetadata": {
63+
"_appLogoUrl": "https://monogame.net",
64+
"_appFaviconPath": "/images/favicon.png",
65+
"_disableBreadcrumb": "true",
66+
"_appFooter": "Copyright © 2009-2025 MonoGame Foundation, Inc.",
67+
"_hostname": "monogame.net",
68+
"_openGraphImage": "images/social_embed_image.png",
69+
"_description": "One framework for creating powerful cross-platform games.",
70+
"_appTitle": "MonoGame",
71+
"_enableSearch": true
72+
},
73+
"template": [
74+
"default",
75+
"modern",
76+
"templates/monogame"
77+
],
78+
"markdownEngineProperties": {
79+
"markdigExtensions": [
80+
"Abbreviations",
81+
"Figures",
82+
"CustomContainers",
83+
"attributes"
84+
]
85+
},
86+
"postProcessors": [],
87+
"keepFileLink": false,
88+
"disableGitFeatures": false,
89+
"sitemap": {
90+
"baseUrl": "https://docs.monogame.net/",
91+
"priority": 0.1,
92+
"changefreq": "monthly"
93+
}
94+
}
95+
}

‎docfx.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,8 @@
44
"src": [
55
{
66
"files": [
7-
"external/MonoGame/MonoGame.Framework/MonoGame.Framework.DesktopGL.csproj",
8-
"external/MonoGame/MonoGame.Framework.Content.Pipeline/MonoGame.Framework.Content.Pipeline.csproj"
7+
"external/MonoGame/Artifacts/MonoGame.Framework/DesktopGL/Debug/MonoGame.Framework.dll",
8+
"external/MonoGame/Artifacts/MonoGame.Framework.Content.Pipeline/Debug/MonoGame.Framework.Content.Pipeline.dll"
99
]
1010
}
1111
],

‎serve.ps1‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Exit on any error
2+
$ErrorActionPreference = "Stop"
3+
4+
# Run the build script to make sure there's something to serve
5+
.\build.ps1
6+
7+
# Start DocFx serve
8+
dotnet docfx docfx.json --serve

‎serve.sh‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
#!/bin/bash
2+
3+
set -e
4+
5+
# Run the build script to make sure there's something to serve
6+
./build.sh
7+
8+
# Start DocFx serve
9+
dotnet docfx docfx.json --serve

0 commit comments

Comments
 (0)