Add DocFx Integration (#3833)

* add docfx files

* master --> main

* Update ownership

* add PR create action

* bias towards powershell

* remove auto-generated toc

* run on pull request

* prepend 'powershell'

* Update publish-docfx.yml

* Setup powershell to run in the workflow

* Update publish-docfx.yml

* update index

* new deployment

* add git fetch

* update git workflow

* update git workflow

* update index

* update git workflow

* chatbot!

* update workflow and nit stuff

* revert submodule changes

* update permissions to just the job

* explicitly set READ permissions

* add conditional commits and concurrency

* update pinned dependency for actions/checkout

* delete root docfx files

* add JIT creation of root files

* integrate JIT into the workflow

* use correct pinned dep for setup-dotnet

* add publish docfx yml to pull_request run

* rm index.md in root

---------

Co-authored-by: Jack He <jackhe@microsoft.com>

.github/workflows/publish-docfx.yml

@@ -0,0 +1,52 @@
+
+name: Deploy DocFx
+
+on:
+  workflow_dispatch:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+    paths: ["docs/**"]
+  
+  pull_request:
+    branches: ["main"]
+    paths: ["docs/**", ".github/workflows/publish-docfx.yml"]
+
+permissions: read-all
+
+concurrency:
+  # Cancel any workflow currently in progress for the same PR.
+  # Allow running concurrently with any other commits.
+  group: deploy-docfx-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: true
+
+jobs:
+  publish-docs:
+    permissions:
+      contents: write
+      pages: write
+      id-token: write
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744
+    - name: Dotnet Setup
+      uses: actions/setup-dotnet@3447fd6a9f9e57506b15f895c5b76d3b197dc7c2
+      with:
+        dotnet-version: 7.x
+
+    - run: dotnet tool update -g docfx
+    - run: chmod +x ./scripts/prepare-docfx.ps1
+    - run: ./scripts/prepare-docfx.ps1
+      shell: pwsh
+    - run: chmod +x ./scripts/generate-docfx-yml.ps1
+    - run: ./scripts/generate-docfx-yml.ps1 ./docs
+      shell: pwsh
+    - run: docfx docfx.json
+
+    - name: Commit Changes
+      if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+      run: |
+          chmod +x ./scripts/update-docfx-site.ps1
+          ./scripts/update-docfx-site.ps1
+          shell: pwsh

.gitignore

@@ -377,3 +377,6 @@ Cargo.lock
 
 # IntelliJ project files
 .idea/
+
+# docfx cache folder
+_site

scripts/generate-docfx-yml.ps1

@@ -0,0 +1,61 @@
+
+# Usage: ./generate-docfx-yml.ps1 <directoryPath>
+#
+# Recursively iterates directoryPath and creates a toc.yml in each subdirectory,
+# generating a table of contents for each markdown file. This is useful for docfx
+# as docfx requires a manifest for just in time static site compilation.
+#
+
+param (
+    [string]$directoryPath
+)
+
+# Check if the powershell-yaml module is installed, and if not, install it
+$module = Get-Module -Name powershell-yaml -ListAvailable
+if ($module -eq $null) {
+    Write-Host "The 'powershell-yaml' module is not installed. Installing it..."
+    Install-Module -Name powershell-yaml -Scope CurrentUser -Force
+}
+
+# Import the powershell-yaml module
+Import-Module powershell-yaml
+
+function CreateTocFile($directory) {
+    $tocPath = Join-Path $directory "toc.yml"
+    $markdownFiles = Get-ChildItem -Path $directory -Filter "*.md" -File
+
+    $tocContent = @()
+    foreach ($file in $markdownFiles) {
+        $name = $file.BaseName
+        $href = $file.Name
+        $tocItem = @{
+            name = $name
+            href = $href
+        }
+        $tocContent += $tocItem
+    }
+
+    if ($tocContent.Count -gt 0) {
+        $tocContent | ConvertTo-Yaml | Out-String | Out-File -FilePath $tocPath -Force
+        Write-Host "Created $tocPath"
+    } else {
+        Write-Host "No markdown files found in $directory. Skipping toc.yml creation."
+    }
+}
+
+function ProcessDirectories($directory) {
+    # Process the current directory
+    CreateTocFile $directory
+
+    # Recursively process subdirectories
+    $subdirectories = Get-ChildItem -Path $directory -Directory
+    foreach ($subdir in $subdirectories) {
+        ProcessDirectories $subdir.FullName
+    }
+}
+
+if (Test-Path -Path $directoryPath -PathType Container) {
+    ProcessDirectories $directoryPath
+} else {
+    Write-Host "Invalid directory path: $directoryPath" -ForegroundColor Red
+}

scripts/prepare-docfx.ps1

@@ -0,0 +1,83 @@
+$jsonContent = @"
+{
+  "metadata": [
+    {
+      "src": [
+        {
+          "files": [
+            "bin/**/*.dll"
+          ]
+        }
+      ],
+      "dest": "api",
+      "includePrivateMembers": false,
+      "disableGitFeatures": false,
+      "disableDefaultFilter": false,
+      "noRestore": false,
+      "namespaceLayout": "flattened",
+      "memberLayout": "samePage",
+      "EnumSortOrder": "alphabetic",
+      "allowCompilationErrors": false
+    }
+  ],
+  "build": {
+    "content": [
+      {
+        "files": [ "**/*.{md,yml}" ],
+        "exclude": [ "_site/**", "obj/**" ]
+      }
+    ],
+    "resource": [
+      {
+        "files": [ "**/images/**", "codesnippet/**" ],
+        "exclude": [ "_site/**", "obj/**" ]
+      }
+    ],
+    "output": "_site",
+    "globalMetadataFiles": [],
+    "fileMetadataFiles": [],
+    "template": [
+      "default",
+      "modern"
+    ],
+    "postProcessors": ["ExtractSearchIndex"],
+    "keepFileLink": false,
+    "disableGitFeatures": false
+  }
+}
+"@
+
+$jsonContent | Out-File -FilePath "docfx.json"
+Write-Host "docfx.json file has been created with the specified contents."
+
+$yamlContent = @"
+- name: MsQuic
+  href: docs/
+
+- name: API
+  href: docs/api/
+"@
+
+$yamlContent | Out-File -FilePath "toc.yml"
+Write-Host "toc.yml file has been created with the specified contents."
+
+$indexMdContent = @"
+# MsQuic Documentation With DocFx:
+
+## Why?
+
+A Better Search Experience.
+
+Taking Advantage of built-in indexing offered by DocFx,
+and the nice UI configuration options (light / dark) mode,
+makes debugging a little less painful.
+
+Try out the search feature!
+
+Try out dark mode!
+
+Chatbot coming soon!
+"@
+
+$indexMdContent | Out-File -FilePath "index.md"
+Write-Host "index.md file has been created with the specified contents."

scripts/update-docfx-site.ps1

@@ -0,0 +1,23 @@
+$env:GIT_REDIRECT_STDERR = '2>&1'
+
+# Checkout the Performance branch (where data and docfx is stored)
+git fetch
+# Stash any changes to the current branch
+git stash
+git checkout performance-dupe
+
+# Commit the output file.
+git config user.email "quicdev@microsoft.com"
+git config user.name "QUIC Dev[bot]"
+
+$folderPath = "./msquicdocs"
+if (Test-Path $folderPath) {
+    Remove-Item $folderPath -Recurse -Force
+}
+
+mv ./_site ./msquicdocs
+git add ./msquicdocs
+git status
+git commit -m "Update DocFx after documentation changes."
+git pull
+git push