diff --git a/.github/workflows/publish-docfx.yml b/.github/workflows/publish-docfx.yml new file mode 100644 index 000000000..b4c785da0 --- /dev/null +++ b/.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 diff --git a/.gitignore b/.gitignore index ae4717d5d..e366b9c7c 100644 --- a/.gitignore +++ b/.gitignore @@ -377,3 +377,6 @@ Cargo.lock # IntelliJ project files .idea/ + +# docfx cache folder +_site diff --git a/scripts/generate-docfx-yml.ps1 b/scripts/generate-docfx-yml.ps1 new file mode 100644 index 000000000..c1421aaf0 --- /dev/null +++ b/scripts/generate-docfx-yml.ps1 @@ -0,0 +1,61 @@ + +# Usage: ./generate-docfx-yml.ps1 +# +# 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 +} diff --git a/scripts/prepare-docfx.ps1 b/scripts/prepare-docfx.ps1 new file mode 100644 index 000000000..e0a215a11 --- /dev/null +++ b/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." diff --git a/scripts/update-docfx-site.ps1 b/scripts/update-docfx-site.ps1 new file mode 100644 index 000000000..5773d8faf --- /dev/null +++ b/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