Add API Documentation Publication to GitHub pages (#524)

Author: gfs

.github/workflows/publish-api-docs.yml

@@ -0,0 +1,54 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Deploy API Documentation to GitHub Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Single deploy job since we're just deploying
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+      # Install .NET and DocFx
+      - name: Setup .NET Core
+        uses: actions/setup-dotnet@v1
+        with:
+          dotnet-version: '7.0.x'
+      - name: Install docfx
+        run: dotnet tool update -g docfx
+      # Build the API docs
+      - name: Run DocFx
+        run: docfx docfx_project/docfx.json
+      # Upload constructed site
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: 'docfx_project/_site'
+      # deploy to GitHub Pages
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

docfx_project/.gitignore

@@ -0,0 +1,11 @@
+###############
+#    folder   #
+###############
+/**/DROP/
+/**/TEMP/
+/**/packages/
+/**/bin/
+/**/obj/
+
+# Generated site
+_site/**

docfx_project/api/.gitignore

@@ -0,0 +1,8 @@
+###############
+#  temp file  #
+###############
+*.yml
+.manifest
+
+# Generated
+Microsoft.DevSkim.*.yml

docfx_project/api/index.md

@@ -0,0 +1,2 @@
+# API Documentation
+This site contains the auto generated API documentation for the DevSkim.

docfx_project/articles/intro.md

@@ -0,0 +1,2 @@
+# DevSkim API Documentation
+This site contains the auto generated API documentation for the DevSkim library components.

docfx_project/articles/toc.yml

@@ -0,0 +1,2 @@
+- name: Introduction
+  href: intro.md

docfx_project/docfx.json

@@ -0,0 +1,57 @@
+{
+  "metadata": [
+    {
+      "src": [
+        {
+          "files": [
+            "Microsoft.DevSkim.csproj"
+          ],
+          "src": "../DevSkim-DotNet/Microsoft.DevSkim"
+        }
+      ],
+      "dest": "api",
+      "includePrivateMembers": false,
+      "disableGitFeatures": false,
+      "disableDefaultFilter": false,
+      "noRestore": false,
+      "namespaceLayout": "flattened",
+      "memberLayout": "samePage",
+      "allowCompilationErrors": false
+    }
+  ],
+  "build": {
+    "content": [
+      {
+        "files": [
+          "api/**.yml",
+          "api/index.md"
+        ]
+      },
+      {
+        "files": [
+          "articles/**.md",
+          "articles/**/toc.yml",
+          "toc.yml",
+          "*.md"
+        ]
+      }
+    ],
+    "resource": [
+      {
+        "files": [
+          "images/**"
+        ]
+      }
+    ],
+    "output": "_site",
+    "globalMetadataFiles": [],
+    "fileMetadataFiles": [],
+    "template": [
+      "default",
+      "modern"
+    ],
+    "postProcessors": [],
+    "keepFileLink": false,
+    "disableGitFeatures": false
+  }
+}

docfx_project/index.md

@@ -0,0 +1,4 @@
+# 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.

docfx_project/toc.yml

@@ -0,0 +1,5 @@
+- name: Articles
+  href: articles/
+- name: Api Documentation
+  href: api/
+  homepage: api/index.md