DocFX documentation (helldivers-2#52)

dealloc · sreece52 · commit e739307d3197 · 2024-04-11T14:39:46.000-04:00
* setup DocFX

install DocFX and setup docfx.json
move OpenAPI specs to docfx files

* disable file serve as wwwroot is empty
diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
@@ -30,28 +30,32 @@ jobs:
         uses: actions/setup-dotnet@v4
         with:
           dotnet-version: 8.0.x
+      - name: Install DocFX
+        run: dotnet tool install -g docfx
       - name: Initial static JSON schema submodule
         run: git submodule update --init ./src/Helldivers-2-Models/json
       - name: Generate OpenAPI JSON files
         run: dotnet build -c Debug
-      - name: Rename Swagger HTML file to index
-        run: mv src/Helldivers-2-API/wwwroot/swagger-ui.html src/Helldivers-2-API/wwwroot/index.html
-      - name: Upload OpenAPI artifact
+      - name: Generate DocFX metadata
+        run: docfx metadata
+      - name: Generate DocFX site
+        run: docfx build docfx.json
+      - name: Upload DocFX website
         uses: actions/upload-artifact@master
         with:
-          name: 'OpenAPI-artifact'
-          path: './src/Helldivers-2-API/wwwroot'
+          name: 'docfx'
+          path: './_site/'
   deploy:
     needs: build
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
     steps:
-      - name: Download generated OpenAPI files
+      - name: Download DocFX website
         uses: actions/download-artifact@master
         with:
-          name: 'OpenAPI-artifact'
+          name: 'docfx'
           path: '.'
       - name: Setup Pages
         uses: actions/configure-pages@v4
diff --git a/.gitignore b/.gitignore
@@ -363,4 +363,11 @@ MigrationBackup/
 FodyWeavers.xsd
 
 # Jetbrains generated folders
-.idea/
+.idea/
+
+# DocFX generates files
+_site/
+api/
+
+# Ignore OpenAPI documents
+docs/openapi/*.json
diff --git a/Helldivers-2.sln b/Helldivers-2.sln
@@ -13,6 +13,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution
 		Directory.Build.props = Directory.Build.props
 		fly.toml = fly.toml
 		.dockerignore = .dockerignore
+		docfx.json = docfx.json
 	EndProjectSection
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Helldivers-2-Models", "src\Helldivers-2-Models\Helldivers-2-Models.csproj", "{9B017849-C756-4B98-9B98-885AEBE9EAD4}"
diff --git a/docfx.json b/docfx.json
@@ -0,0 +1,46 @@
+{
+  "metadata": [
+    {
+      "src": [
+        {
+          "files": [
+            "**/*.csproj"
+          ]
+        }
+      ],
+      "dest": "api"
+    }
+  ],
+  "build": {
+    "content": [
+      {
+        "files": [
+          "**/*.{md,yml}"
+        ],
+        "exclude": [
+          "_site/**",
+          "src/Helldivers-2-Models/json/**"
+        ]
+      }
+    ],
+    "resource": [
+      {
+        "files": [
+          "images/**",
+          "docs/openapi/**"
+        ]
+      }
+    ],
+    "output": "_site",
+    "template": [
+      "default",
+      "modern"
+    ],
+    "globalMetadata": {
+      "_appName": "Helldivers-2 API",
+      "_appTitle": "Helldivers-2 API",
+      "_enableSearch": true,
+      "pdf": false
+    }
+  }
+}
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -0,0 +1 @@
+# Getting Started
diff --git a/docs/introduction.md b/docs/introduction.md
@@ -0,0 +1 @@
+# Introduction
diff --git a/docs/openapi/redoc.html b/docs/openapi/redoc.html
diff --git a/docs/openapi/swagger-ui.html b/docs/openapi/swagger-ui.html
diff --git a/docs/toc.yml b/docs/toc.yml
@@ -0,0 +1,12 @@
+- name: Introduction
+  href: introduction.md
+- name: Getting Started
+  href: getting-started.md
+- name: SwaggerUI
+  href: ./openapi/swagger-ui.html
+- name: Contributing
+  href: ../contributing.md
+- name: Code of conduct
+  href: ../CODE_OF_CONDUCT.md
+- name: Reporting vulnerabilities
+  href: ../SECURITY.md
diff --git a/index.md b/index.md
@@ -0,0 +1,11 @@
+---
+_layout: landing
+---
+
+# This is the **HOMEPAGE**.
+
+Refer to [Markdown](http://daringfireball.net/projects/markdown/) for how to write markdown files.
+
+## Quick Start Notes:
+
+1. Add images to the *images* folder if the file is referencing an image.
diff --git a/src/Helldivers-2-API/Helldivers-2-API.csproj b/src/Helldivers-2-API/Helldivers-2-API.csproj
@@ -10,7 +10,7 @@
 
     <!-- Only generate OpenAPI docs for DEBUG builds -->
     <PropertyGroup Condition="'$(Configuration)' == 'Debug'">
-        <OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)/wwwroot</OpenApiDocumentsDirectory>
+        <OpenApiDocumentsDirectory>$(SolutionDir)/docs/openapi</OpenApiDocumentsDirectory>
         <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
         <OpenApiGenerateDocumentsOnBuild>true</OpenApiGenerateDocumentsOnBuild>
     </PropertyGroup>
diff --git a/src/Helldivers-2-API/Program.cs b/src/Helldivers-2-API/Program.cs
@@ -145,9 +145,6 @@
 // Use response compression for smaller payload sizes
 app.UseResponseCompression();
 
-// We host our OpenAPI spec and preview files from wwwroot/
-app.UseStaticFiles();
-
 // select the correct culture for incoming requests
 app.UseRequestLocalization();
 
diff --git a/src/Helldivers-2-API/wwwroot/Helldivers-2-API.json b/src/Helldivers-2-API/wwwroot/Helldivers-2-API.json
diff --git a/src/Helldivers-2-API/wwwroot/Helldivers-2-API_arrowhead.json b/src/Helldivers-2-API/wwwroot/Helldivers-2-API_arrowhead.json
diff --git a/toc.yml b/toc.yml
