From 59d0b8e94b2a4ceab823381d2a8bcc57303e3a6e Mon Sep 17 00:00:00 2001 From: Gabe Stocco <98900+gfs@users.noreply.github.com> Date: Tue, 23 May 2023 19:12:03 +0000 Subject: [PATCH] Add API Documentation Publication to GitHub pages (#524) --- .github/workflows/publish-api-docs.yml | 54 ++++++++++++++++++++++++ docfx_project/.gitignore | 11 +++++ docfx_project/api/.gitignore | 8 ++++ docfx_project/api/index.md | 2 + docfx_project/articles/intro.md | 2 + docfx_project/articles/toc.yml | 2 + docfx_project/docfx.json | 57 ++++++++++++++++++++++++++ docfx_project/index.md | 4 ++ docfx_project/toc.yml | 5 +++ 9 files changed, 145 insertions(+) create mode 100644 .github/workflows/publish-api-docs.yml create mode 100644 docfx_project/.gitignore create mode 100644 docfx_project/api/.gitignore create mode 100644 docfx_project/api/index.md create mode 100644 docfx_project/articles/intro.md create mode 100644 docfx_project/articles/toc.yml create mode 100644 docfx_project/docfx.json create mode 100644 docfx_project/index.md create mode 100644 docfx_project/toc.yml diff --git a/.github/workflows/publish-api-docs.yml b/.github/workflows/publish-api-docs.yml new file mode 100644 index 0000000..74b1240 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/docfx_project/.gitignore b/docfx_project/.gitignore new file mode 100644 index 0000000..26e2821 --- /dev/null +++ b/docfx_project/.gitignore @@ -0,0 +1,11 @@ +############### +# folder # +############### +/**/DROP/ +/**/TEMP/ +/**/packages/ +/**/bin/ +/**/obj/ + +# Generated site +_site/** \ No newline at end of file diff --git a/docfx_project/api/.gitignore b/docfx_project/api/.gitignore new file mode 100644 index 0000000..426692c --- /dev/null +++ b/docfx_project/api/.gitignore @@ -0,0 +1,8 @@ +############### +# temp file # +############### +*.yml +.manifest + +# Generated +Microsoft.DevSkim.*.yml \ No newline at end of file diff --git a/docfx_project/api/index.md b/docfx_project/api/index.md new file mode 100644 index 0000000..f86138b --- /dev/null +++ b/docfx_project/api/index.md @@ -0,0 +1,2 @@ +# API Documentation +This site contains the auto generated API documentation for the DevSkim. \ No newline at end of file diff --git a/docfx_project/articles/intro.md b/docfx_project/articles/intro.md new file mode 100644 index 0000000..befaf00 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docfx_project/articles/toc.yml b/docfx_project/articles/toc.yml new file mode 100644 index 0000000..ff89ef1 --- /dev/null +++ b/docfx_project/articles/toc.yml @@ -0,0 +1,2 @@ +- name: Introduction + href: intro.md diff --git a/docfx_project/docfx.json b/docfx_project/docfx.json new file mode 100644 index 0000000..06fe363 --- /dev/null +++ b/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 + } +} \ No newline at end of file diff --git a/docfx_project/index.md b/docfx_project/index.md new file mode 100644 index 0000000..3ae2506 --- /dev/null +++ b/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. diff --git a/docfx_project/toc.yml b/docfx_project/toc.yml new file mode 100644 index 0000000..59f8010 --- /dev/null +++ b/docfx_project/toc.yml @@ -0,0 +1,5 @@ +- name: Articles + href: articles/ +- name: Api Documentation + href: api/ + homepage: api/index.md