From 78ff0c121787cd5016c1ac6001925be04dc3603b Mon Sep 17 00:00:00 2001 From: Dean Ellis Date: Wed, 4 Feb 2026 17:27:34 +0000 Subject: [PATCH] Fix the missing API Reference Table of Contents --- .github/workflows/main.yml | 15 ++++-- build.ps1 | 16 ++++-- build.sh | 15 ++++-- docfx.json | 2 - docfx.pdf.json | 100 +++++++++++++++++++++++++++++++++++++ serve.ps1 | 2 +- serve.sh | 2 +- 7 files changed, 135 insertions(+), 17 deletions(-) mode change 100644 => 100755 build.sh create mode 100644 docfx.pdf.json mode change 100644 => 100755 serve.sh diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 829a9f0f..e83fa972 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -42,17 +42,24 @@ jobs: - name: Restore dotnet tools run: dotnet tool restore + - name: Run Metadata Build + run: dotnet docfx metadata ci.docfx.json + - name: Run Build - run: dotnet docfx ci.docfx.json + run: dotnet docfx build ci.docfx.json + + - name: Create PDF build folder + run: | + mkdir -p _pdf - name: Generate PDF - run: dotnet docfx pdf ci.docfx.json + run: dotnet docfx pdf docfx.pdf.json --output _pdf - name: Copy PDF to downloads and clean up run: | mkdir -p _site/downloads - cp _site/pdf/MonoGameGuide.pdf _site/downloads/ - rm -rf _site/pdf + cp _pdf/pdf/MonoGameGuide.pdf _site/downloads/ + rm -rf _pdf - name: Setup Pages uses: actions/configure-pages@v5 diff --git a/build.ps1 b/build.ps1 index b3ee9750..1e42f8cc 100644 --- a/build.ps1 +++ b/build.ps1 @@ -19,16 +19,22 @@ if (-not (Test-Path $FrameworkDll) -or -not (Test-Path $PipelineDll)) { # Build documentation Write-Host "Building DocFx..." -ForegroundColor Green -dotnet docfx docfx.json +dotnet docfx metadata docfx.json -# Generate PDF +# Build documentation +Write-Host "Building DocFx..." -ForegroundColor Green +dotnet docfx build docfx.json + +New-Item -ItemType Directory -Force -Path "_pdf" | Out-Null + +# Generate PDF (using PDF-specific config that includes pdf/** files) Write-Host "Generating PDF..." -ForegroundColor Green -dotnet docfx pdf docfx.json +dotnet docfx pdf docfx.pdf.json --output _pdf # Copy PDF to downloads folder and clean up Write-Host "Copying PDF to downloads folder..." -ForegroundColor Green New-Item -ItemType Directory -Force -Path "_site/downloads" | Out-Null -Copy-Item "_site/pdf/MonoGameGuide.pdf" "_site/downloads/" -Remove-Item -Path "_site/pdf" -Recurse -Force +Copy-Item "_pdf/pdf/MonoGameGuide.pdf" "_site/downloads/" +Remove-Item -Path "_pdf" -Recurse -Force Write-Host "Build and documentation generation completed successfully!" -ForegroundColor Green \ No newline at end of file diff --git a/build.sh b/build.sh old mode 100644 new mode 100755 index 6f2876dc..8793f26a --- a/build.sh +++ b/build.sh @@ -17,18 +17,25 @@ if [ ! -f "$FRAMEWORK_DLL" ] || [ ! -f "$PIPELINE_DLL" ]; then dotnet build external/MonoGame/MonoGame.Framework.Content.Pipeline/MonoGame.Framework.Content.Pipeline.csproj -p:DisableNativeBuild=true fi +# Build documentation +echo "Building DocFx..." +dotnet docfx metadata docfx.json + # Build documentation echo "Building DocFx..." dotnet docfx docfx.json -# Generate PDF +mkdir -p _pdf + +# Generate PDF (using PDF-specific config that includes pdf/** files) echo "Generating PDF..." -dotnet docfx pdf docfx.json +dotnet docfx build docfx.pdf.json --output _pdf +dotnet docfx pdf docfx.pdf.json --output _pdf # Copy PDF to downloads folder and clean up echo "Copying PDF to downloads folder..." mkdir -p _site/downloads -cp _site/pdf/MonoGameGuide.pdf _site/downloads/ -rm -rf _site/pdf +cp _pdf/pdf/MonoGameGuide.pdf _site/downloads/ +rm -rf _pdf echo "Build and documentation generation completed successfully!" \ No newline at end of file diff --git a/docfx.json b/docfx.json index fa0f11f1..4efa5a1d 100644 --- a/docfx.json +++ b/docfx.json @@ -42,8 +42,6 @@ "roadmap/**/*.md", "roadmap/**/*.yml", "errors/**/*.md", - "pdf/**/*.md", - "pdf/**/*.yml", "toc.yml", "*.md" ], diff --git a/docfx.pdf.json b/docfx.pdf.json new file mode 100644 index 00000000..f16a408d --- /dev/null +++ b/docfx.pdf.json @@ -0,0 +1,100 @@ +{ + "metadata": [ + { + "src": [ + { + "files": [ + "external/MonoGame/Artifacts/MonoGame.Framework/DesktopGL/Debug/MonoGame.Framework.dll", + "external/MonoGame/Artifacts/MonoGame.Framework.Content.Pipeline/Debug/MonoGame.Framework.Content.Pipeline.dll" + ] + } + ], + "dest": "api", + "filter": "filterConfig.yml", + "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", + "pdf/**/*.md", + "pdf/**/*.yml", + "toc.yml", + "*.md" + ], + "exclude": [ "_site/**", "README.md" ] + } + ], + "resource": [ + { + "files": [ + "**/images/**", + "**/videos/**", + "**/files/**", + "**/snippets/**", + "**/*.docx", + "CNAME" + ] + } + ], + "output": "_site", + "globalMetadata": { + "_appLogoUrl": "https://monogame.net", + "_appFaviconPath": "/images/favicon.png", + "_disableBreadcrumb": "true", + "_appFooter": "Copyright © 2009-2026 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, + "pdfFooterTemplate": "
MonoGame Complete Reference GuidePage of
" + }, + "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" + } + } +} diff --git a/serve.ps1 b/serve.ps1 index 589eebe6..56d27fe0 100644 --- a/serve.ps1 +++ b/serve.ps1 @@ -5,4 +5,4 @@ $ErrorActionPreference = "Stop" .\build.ps1 # Start DocFx serve -dotnet docfx docfx.json --serve \ No newline at end of file +dotnet docfx serve .\_site \ No newline at end of file diff --git a/serve.sh b/serve.sh old mode 100644 new mode 100755 index ce05a254..75a0d906 --- a/serve.sh +++ b/serve.sh @@ -6,4 +6,4 @@ set -e ./build.sh # Start DocFx serve -dotnet docfx docfx.json --serve \ No newline at end of file +dotnet docfx serve _site \ No newline at end of file