Update C# documentation #1540
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: Documentation | |
| on: | |
| workflow_dispatch: | |
| inputs: | |
| environment: | |
| description: 'Where to deploy changes' | |
| required: true | |
| default: 'dev' | |
| type: choice | |
| options: | |
| - dev | |
| - prod | |
| regen-artifacts: | |
| description: 'Regenerate artifacts (when expired or missing)' | |
| required: false | |
| type: boolean | |
| repository_dispatch: | |
| types: | |
| - Update JS documentation | |
| - Update C# documentation | |
| - Update SDK documentation | |
| - Update GTA documentation | |
| env: | |
| PRODUCTION: ${{ github.event.inputs.environment == 'prod' || github.event.action != '' }} | |
| concurrency: ${{ github.workflow }}-${{ github.ref }} | |
| jobs: | |
| bootstrap: | |
| runs-on: ubuntu-latest | |
| outputs: | |
| isSkipped: ${{ steps.cond-run.outputs.isSkipped }} | |
| steps: | |
| - name: Conditional run | |
| id: cond-run | |
| run: | | |
| REGENERATE="${{ github.event.inputs.regen-artifacts }}" | |
| ARTIFACTS=() | |
| EVENT="${{ github.event.action }}" | |
| declare -A ARTIFACTS_DEF=( | |
| ["Update JS documentation"]="js" | |
| ["Update C# documentation"]="cs" | |
| ["Update SDK documentation"]="sdk" | |
| ["Update GTA documentation"]="gta" | |
| ) | |
| if [ "$REGENERATE" = "true" ]; then | |
| echo "::set-output name=isSkipped::false" | |
| exit | |
| fi | |
| for name in "${!ARTIFACTS_DEF[@]}"; do | |
| if [[ "$EVENT" = "$name" ]]; then | |
| ARTIFACTS+=("${ARTIFACTS_DEF[$name]}") | |
| break | |
| fi | |
| done | |
| echo "::set-output name=isSkipped::${ARTIFACTS[@]}" | |
| js: | |
| runs-on: windows-2019 | |
| needs: bootstrap | |
| if: ${{ needs.bootstrap.outputs.isSkipped == 'false' || contains(needs.bootstrap.outputs.isSkipped, 'js') }} | |
| env: | |
| SOURCE_BRANCH: ${{ github.event.client_payload && github.event.client_payload.sha || 'master' }} | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@v3 | |
| with: | |
| persist-credentials: false | |
| - name: Load version manifest | |
| uses: tw3lveparsecs/[email protected] | |
| with: | |
| envFilePath: ./.github/variables/vars.env | |
| - name: Setup Node.js | |
| uses: actions/setup-node@v3 | |
| with: | |
| node-version: 16.x | |
| - name: Checkout repository | |
| uses: actions/checkout@v3 | |
| with: | |
| persist-credentials: false | |
| repository: altmp/altv-types | |
| ref: ${{ env.SOURCE_BRANCH }} | |
| path: ./altv-types | |
| - name: Checkout latest commit | |
| run: git checkout $(git rev-parse HEAD) | |
| working-directory: ./altv-types | |
| - name: Install dependencies | |
| run: | | |
| Set-Location -Path "./altv-types/docs/" | |
| yarn install | |
| - name: Generate JS metadata | |
| run: | | |
| Set-Location -Path "./altv-types/docs/" | |
| Push-Location -Path "../" | |
| npx typedoc --options "./docs/typedoc.json" | |
| Pop-Location | |
| npx type2docfx "./api/.manifest" "./api/" --basePath "." --sourceUrl "https://github.com/altmp/altv-types" --sourceBranch "${{ env.SOURCE_BRANCH }}" --tocAlphabetOrderOnly | |
| - name: Upload artifacts | |
| uses: actions/upload-artifact@v3 | |
| if: "env.PRODUCTION == 'true'" | |
| with: | |
| name: js | |
| path: ./altv-types/docs/ | |
| - name: Upload artifacts | |
| uses: actions/upload-artifact@v3 | |
| if: "env.PRODUCTION == 'false'" | |
| with: | |
| name: nightly-js | |
| path: ./altv-types/docs/ | |
| cs: | |
| runs-on: windows-2019 | |
| needs: bootstrap | |
| if: ${{ needs.bootstrap.outputs.isSkipped == 'false' || contains(needs.bootstrap.outputs.isSkipped, 'cs') }} | |
| env: | |
| SOURCE_BRANCH: ${{ github.event.client_payload && github.event.client_payload.sha || 'dev' }} | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@v3 | |
| with: | |
| persist-credentials: false | |
| - name: Load version manifest | |
| uses: tw3lveparsecs/[email protected] | |
| with: | |
| envFilePath: ./.github/variables/vars.env | |
| - name: Checkout repository | |
| uses: actions/checkout@v3 | |
| with: | |
| persist-credentials: false | |
| repository: FabianTerhorst/coreclr-module | |
| ref: ${{ env.SOURCE_BRANCH }} | |
| path: ./coreclr-module | |
| - name: Checkout latest commit | |
| run: git checkout $(git rev-parse HEAD) | |
| working-directory: ./coreclr-module | |
| - name: Download DocFx package | |
| uses: robinraju/[email protected] | |
| with: | |
| repository: dotnet/docfx | |
| tag: ${{ env.DOCFX }} | |
| fileName: docfx.zip | |
| - name: Unzip DocFx package | |
| run: | | |
| Expand-Archive -Path "./docfx.zip" -DestinationPath "./docfx/" | |
| Remove-Item -Path "./docfx.zip" | |
| - name: Generate C# metadata | |
| run: ./docfx/docfx metadata "./coreclr-module/docs/docfx.json" | |
| - name: Upload artifacts | |
| uses: actions/upload-artifact@v3 | |
| if: "env.PRODUCTION == 'true'" | |
| with: | |
| name: cs | |
| path: ./coreclr-module/docs/ | |
| - name: Upload artifacts | |
| uses: actions/upload-artifact@v3 | |
| if: "env.PRODUCTION == 'false'" | |
| with: | |
| name: nightly-cs | |
| path: ./coreclr-module/docs/ | |
| sdk: | |
| runs-on: windows-2019 | |
| needs: bootstrap | |
| if: ${{ needs.bootstrap.outputs.isSkipped == 'false' || contains(needs.bootstrap.outputs.isSkipped, 'sdk') }} | |
| env: | |
| SOURCE_BRANCH: ${{ github.event.client_payload && github.event.client_payload.sha || 'docs' }} | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@v3 | |
| with: | |
| persist-credentials: false | |
| - name: Load version manifest | |
| uses: tw3lveparsecs/[email protected] | |
| with: | |
| envFilePath: ./.github/variables/vars.env | |
| - name: Checkout repository | |
| uses: actions/checkout@v3 | |
| with: | |
| persist-credentials: false | |
| repository: altmp/cpp-sdk | |
| ref: ${{ env.SOURCE_BRANCH }} | |
| path: ./cpp-sdk | |
| - name: Checkout latest commit | |
| run: git checkout $(git rev-parse HEAD) | |
| working-directory: ./cpp-sdk | |
| - name: Upload artifacts | |
| uses: actions/upload-artifact@v3 | |
| if: "env.PRODUCTION == 'true'" | |
| with: | |
| name: sdk | |
| path: ./cpp-sdk/articles/ | |
| - name: Upload artifacts | |
| uses: actions/upload-artifact@v3 | |
| if: "env.PRODUCTION == 'false'" | |
| with: | |
| name: nightly-sdk | |
| path: ./cpp-sdk/articles/ | |
| gta: | |
| runs-on: windows-latest | |
| needs: bootstrap | |
| if: ${{ needs.bootstrap.outputs.isSkipped == 'false' || contains(needs.bootstrap.outputs.isSkipped, 'gta') }} | |
| env: | |
| SOURCE_BRANCH: ${{ github.event.client_payload && github.event.client_payload.sha || 'master' }} | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@v3 | |
| with: | |
| persist-credentials: false | |
| - name: Load version manifest | |
| uses: tw3lveparsecs/[email protected] | |
| with: | |
| envFilePath: ./.github/variables/vars.env | |
| - name: Checkout repository | |
| uses: actions/checkout@v3 | |
| with: | |
| persist-credentials: false | |
| repository: altmp/altv-docs-gta | |
| ref: ${{ env.SOURCE_BRANCH }} | |
| path: ./altv-docs-gta | |
| - name: Checkout latest commit | |
| run: git checkout $(git rev-parse HEAD) | |
| working-directory: ./altv-docs-gta | |
| - name: Install dependencies | |
| run: exit 0 | |
| - name: Generate GTA metadata | |
| run: exit 0 | |
| - name: Upload artifacts | |
| uses: actions/upload-artifact@v3 | |
| if: "env.PRODUCTION == 'true'" | |
| with: | |
| name: gta | |
| path: | | |
| ./altv-docs-gta/api | |
| ./altv-docs-gta/articles | |
| - name: Upload artifacts | |
| uses: actions/upload-artifact@v3 | |
| if: "env.PRODUCTION == 'false'" | |
| with: | |
| name: nightly-gta | |
| path: | | |
| ./altv-docs-gta/api | |
| ./altv-docs-gta/articles | |
| docs: | |
| runs-on: windows-2019 | |
| needs: | |
| - js | |
| - cs | |
| - sdk | |
| - gta | |
| if: always() | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@v3 | |
| with: | |
| persist-credentials: false | |
| - name: Load version manifest | |
| uses: tw3lveparsecs/[email protected] | |
| with: | |
| envFilePath: ./.github/variables/vars.env | |
| - name: Setup Node.js | |
| uses: actions/setup-node@v3 | |
| with: | |
| node-version: 16.x | |
| - name: Checkout JS repository | |
| uses: actions/checkout@v3 | |
| with: | |
| persist-credentials: false | |
| repository: altmp/altv-types | |
| path: ./altv-types | |
| - name: Checkout C# repository | |
| uses: actions/checkout@v3 | |
| with: | |
| persist-credentials: false | |
| repository: FabianTerhorst/coreclr-module | |
| path: ./coreclr-module | |
| - name: Checkout SDK repository | |
| uses: actions/checkout@v3 | |
| with: | |
| persist-credentials: false | |
| repository: altmp/cpp-sdk | |
| ref: docs | |
| path: ./cpp-sdk | |
| - name: Checkout GTA repository | |
| uses: actions/checkout@v3 | |
| with: | |
| persist-credentials: false | |
| repository: altmp/altv-docs-gta | |
| path: ./altv-docs-gta | |
| - name: Checkout assets repository | |
| uses: actions/checkout@v3 | |
| with: | |
| persist-credentials: false | |
| repository: altmp/altv-docs-assets | |
| ref: deploy | |
| path: ./altv-docs-assets | |
| - name: Download DocFx package | |
| uses: robinraju/[email protected] | |
| with: | |
| repository: dotnet/docfx | |
| tag: ${{ env.DOCFX }} | |
| fileName: docfx.zip | |
| - name: Unzip DocFx package | |
| run: | | |
| Expand-Archive -Path "./docfx.zip" -DestinationPath "./docfx/" | |
| Remove-Item -Path "docfx.zip" | |
| - name: Download DocFx TypeScriptReference package | |
| uses: robinraju/[email protected] | |
| with: | |
| repository: Unnvaldr/DocFx.Plugins.TypeScriptReference | |
| tag: ${{ env.DOCFX_PLUGINS_TYPESCRIPTREFERENCE }} | |
| fileName: docfx-plugins-typescriptreference.zip | |
| - name: Unzip DocFx TypeScriptReference package | |
| run: | | |
| Expand-Archive -Path "./docfx-plugins-typescriptreference.zip" -DestinationPath "./templates/" | |
| Remove-Item -Path "./docfx-plugins-typescriptreference.zip" | |
| - name: Download DocFx ExtractSearchIndex package | |
| uses: robinraju/[email protected] | |
| with: | |
| repository: Unnvaldr/DocFx.Plugins.ExtractSearchIndex | |
| tag: ${{ env.DOCFX_PLUGINS_EXTRACTSEARCHINDEX }} | |
| fileName: docfx-plugins-extractsearchindex.zip | |
| - name: Unzip DocFx ExtractSearchIndex package | |
| run: | | |
| Expand-Archive -Path "./docfx-plugins-extractsearchindex.zip" -DestinationPath "./templates/" | |
| Remove-Item -Path "./docfx-plugins-extractsearchindex.zip" | |
| - name: Download DocFx AddImageModal package | |
| uses: robinraju/[email protected] | |
| with: | |
| repository: Unnvaldr/DocFx.Plugins.AddImageModal | |
| tag: ${{ env.DOCFX_PLUGINS_ADDIMAGEMODAL }} | |
| fileName: docfx-plugins-addimagemodal.zip | |
| - name: Unzip DocFx AddImageModal package | |
| run: | | |
| Expand-Archive -Path "./docfx-plugins-addimagemodal.zip" -DestinationPath "./templates/" | |
| Remove-Item -Path "./docfx-plugins-addimagemodal.zip" | |
| - name: Download DocFx ExtractArticleAffix package | |
| uses: robinraju/[email protected] | |
| with: | |
| repository: Unnvaldr/DocFx.Plugins.ExtractArticleAffix | |
| tag: ${{ env.DOCFX_PLUGINS_EXTRACTARTICLEAFFIX }} | |
| fileName: docfx-plugins-extractarticleaffix.zip | |
| - name: Unzip DocFx ExtractArticleAffix package | |
| run: | | |
| Expand-Archive -Path "./docfx-plugins-extractarticleaffix.zip" -DestinationPath "./templates/" | |
| Remove-Item -Path "./docfx-plugins-extractarticleaffix.zip" | |
| - name: Download DocFx DiscordFx package | |
| uses: robinraju/[email protected] | |
| with: | |
| repository: Unnvaldr/DiscordFx | |
| tag: ${{ env.DOCFX_TMPLS_DISCORDFX }} | |
| fileName: docfx-tmpls-discordfx.zip | |
| - name: Unzip DocFx DiscordFx package | |
| run: | | |
| Expand-Archive -Path "./docfx-tmpls-discordfx.zip" -DestinationPath "./templates/" | |
| Remove-Item -Path "./docfx-tmpls-discordfx.zip" | |
| - run: npm install adm-zip | |
| - name: Download latest artifacts | |
| uses: actions/github-script@v6 | |
| with: | |
| script: | | |
| const AdmZip = require("adm-zip"); | |
| const fs = require("fs"); | |
| const path = require("path"); | |
| const isProduction = ${{ env.PRODUCTION }}; | |
| const devPrefix = !isProduction ? 'nightly-' : ''; | |
| const artifactNames = ["js", "cs", "sdk", "gta"].map(name => devPrefix + name); | |
| const artifacts = (await github.rest.actions.listArtifactsForRepo({ | |
| owner: context.repo.owner, | |
| repo: context.repo.repo, | |
| run_id: context.runId | |
| })).data.artifacts; | |
| if (!artifacts.length) { | |
| console.log("No artifacts found"); | |
| return; | |
| } | |
| for (const artifact of artifactNames.map(el => artifacts.find(el2 => el2.name === el))) { | |
| if (!artifact || artifact.expired) continue; | |
| console.log("==> Artifact:", artifact.id); | |
| console.log(`==> Downloading: ${artifact.name}.zip (${(artifact.size_in_bytes / 1000000).toFixed(2)}MB)`); | |
| const zip = await github.rest.actions.downloadArtifact({ | |
| owner: context.repo.owner, | |
| repo: context.repo.repo, | |
| artifact_id: artifact.id, | |
| archive_format: "zip" | |
| }); | |
| const filePath = path.join("./", artifact.name); | |
| const adm = new AdmZip(Buffer.from(zip.data)); | |
| adm.getEntries().forEach((entry) => { | |
| const action = entry.isDirectory ? "creating" : "inflating"; | |
| console.log(` ${action}: ${path.join(filePath, entry.entryName)}`); | |
| }) | |
| adm.extractAllTo(filePath, true); | |
| } | |
| - name: Download run artifacts | |
| uses: actions/download-artifact@v3 | |
| - name: Unpack artifacts | |
| run: | | |
| $isProduction=$${{ env.PRODUCTION }} | |
| $devPrefix=if (-not $isProduction) { 'nightly-' } else { '' } | |
| Remove-Item -Path "./altv-types/docs/" -Recurse | |
| if(-not (Test-Path -Path "./$($devPrefix)js/js.tar")) { | |
| Move-Item -Path "./$($devPrefix)js/" -Destination "./altv-types/docs" | |
| } else { | |
| Move-Item -Path "./$($devPrefix)js/$($devPrefix)js.tar" -Destination "./altv-types/$($devPrefix)js.tar" | |
| tar -xvf "./altv-types/$($devPrefix)js.tar" -C "./altv-types/" | |
| Remove-Item -Path "./altv-types/$($devPrefix)js.tar" | |
| } | |
| if([System.String]::IsNullOrWhiteSpace((Get-Content -Path "altv-types\docs\api\.manifest" -ErrorAction SilentlyContinue))) { | |
| throw "Invalid altv-types repo manifest." | |
| } | |
| Remove-Item -Path "./coreclr-module/docs/" -Recurse | |
| if(-not (Test-Path -Path "./$($devPrefix)cs/$($devPrefix)cs.tar")) { | |
| Move-Item -Path "./$($devPrefix)cs/" -Destination "./coreclr-module/docs" | |
| } else { | |
| Move-Item -Path "./$($devPrefix)cs/$($devPrefix)cs.tar" -Destination "./coreclr-module/$($devPrefix)cs.tar" | |
| tar -xvf "./coreclr-module/$($devPrefix)cs.tar" -C "./coreclr-module/" | |
| Remove-Item -Path "./coreclr-module/$($devPrefix)cs.tar" | |
| } | |
| if([System.String]::IsNullOrWhiteSpace((Get-Content -Path "coreclr-module\docs\api\.manifest" -ErrorAction SilentlyContinue))) { | |
| throw "Invalid coreclr-module repo manifest." | |
| } | |
| Remove-Item -Path "./cpp-sdk/articles/" -Recurse | |
| if(-not (Test-Path -Path "./$($devPrefix)sdk/$($devPrefix)sdk.tar")) { | |
| Move-Item -Path "./$($devPrefix)sdk/" -Destination "./cpp-sdk/articles" | |
| } else { | |
| Move-Item -Path "./$($devPrefix)sdk/$($devPrefix)sdk.tar" -Destination "./cpp-sdk/$($devPrefix)sdk.tar" | |
| tar -xvf "./cpp-sdk/$($devPrefix)sdk.tar" -C "./cpp-sdk/" | |
| Remove-Item -Path "./cpp-sdk/$($devPrefix)sdk.tar" | |
| } | |
| Remove-Item -Path "./altv-docs-gta/api/" -Recurse | |
| Remove-Item -Path "./altv-docs-gta/articles/" -Recurse | |
| if(-not (Test-Path -Path "./$($devPrefix)gta/$($devPrefix)gta.tar")) { | |
| Move-Item -Path "./$($devPrefix)gta/api/" -Destination "./altv-docs-gta/api/" | |
| Move-Item -Path "./$($devPrefix)gta/articles/" -Destination "./altv-docs-gta/articles/" | |
| } else { | |
| Move-Item -Path "./$($devPrefix)gta/$($devPrefix)gta.tar" -Destination "./altv-docs-gta/$($devPrefix)gta.tar" | |
| tar -xvf "./altv-docs-gta/$($devPrefix)gta.tar" -C "./altv-docs-gta/" | |
| Remove-Item -Path "./altv-docs-gta/$($devPrefix)gta.tar" | |
| } | |
| - name: Build docs | |
| run: ./docfx/docfx "./docfx.json" | |
| - name: Prepare artifact | |
| run: | | |
| Remove-Item -Path "./_site/gta/images" -Recurse -Force | |
| Compress-Archive -Path "./_site/" -DestinationPath "./site.zip" | |
| - name: Upload artifacts | |
| uses: actions/upload-artifact@v3 | |
| if: "env.PRODUCTION == 'true'" | |
| with: | |
| name: site | |
| path: | | |
| ./site.zip | |
| - name: Upload artifacts | |
| uses: actions/upload-artifact@v3 | |
| if: "env.PRODUCTION == 'false'" | |
| with: | |
| name: nightly-site | |
| path: | | |
| ./site.zip | |
| deploy: | |
| name: Deploy GitHub Pages | |
| runs-on: ubuntu-20.04 | |
| needs: | |
| - docs | |
| if: always() && needs.docs.result == 'success' | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@v3 | |
| with: | |
| persist-credentials: false | |
| - name: Checkout assets repository | |
| uses: actions/checkout@v3 | |
| with: | |
| persist-credentials: false | |
| repository: altmp/altv-docs-assets | |
| path: ./altv-docs-assets | |
| - name: Download artifact | |
| uses: actions/download-artifact@v3 | |
| if: "env.PRODUCTION == 'true'" | |
| with: | |
| name: site | |
| path: "." | |
| - name: Download artifact | |
| uses: actions/download-artifact@v3 | |
| if: "env.PRODUCTION == 'false'" | |
| with: | |
| name: nightly-site | |
| path: "." | |
| - name: Prepare artifact | |
| run: | | |
| unzip "./site.zip" | |
| - name: Copy assets to output site | |
| run: | | |
| shopt -s dotglob # Obligatory | |
| DOCFX_CFG=$(cat "./docfx.json") | |
| find "altv-docs-assets/" -mindepth 1 -maxdepth 1 -type "d" ! -name '.*' -print0 | while read -d $'\0' file | |
| do | |
| DEST=$(echo "$DOCFX_CFG" | jq -r --arg path "$file" '.build .resource[] | select(.src==$path) | .dest') | |
| if [ -n "$DEST" ]; then | |
| echo "Destination path \"$DEST\" found for \"$file\"" | |
| for dir in "$file"/*; do | |
| dirDest="./_site/$DEST/"$(basename "$dir") | |
| if [ ! -d "$dirDest" ]; then | |
| mkdir "$dirDest" | |
| fi | |
| mv "$dir"/* "$dirDest" | |
| done | |
| else | |
| echo "Destination path not found for \"$file\"" | |
| fi | |
| done | |
| ls -Rl ./_site/*/images | |
| - name: Deploy page | |
| uses: peaceiris/actions-gh-pages@v3 | |
| if: "env.PRODUCTION == 'true'" | |
| with: | |
| deploy_key: ${{ secrets.RELEASE_PRIVATE_KEY }} | |
| publish_dir: ./_site | |
| external_repository: altmp/altv-docs-release | |
| full_commit_message: Deploying to gh-pages from @ ${{ github.sha }} 🚀 | |
| force_orphan: false | |
| cname: docs.altv.mp | |
| - name: Deploy page | |
| uses: peaceiris/actions-gh-pages@v3 | |
| if: "env.PRODUCTION == 'false'" | |
| with: | |
| deploy_key: ${{ secrets.NIGHTLY_PRIVATE_KEY }} | |
| publish_dir: ./_site | |
| external_repository: altmp/altv-docs-nightly | |
| full_commit_message: Deploying to gh-pages from @ ${{ github.sha }} 🚀 | |
| force_orphan: false | |
| - name: Post Download artifacts | |
| if: ${{ always() }} | |
| uses: geekyeggo/delete-artifact@v2 | |
| with: | |
| name: site | |
| - name: Purge older artifacts | |
| uses: Unnvaldr/actions-purge-artifacts@master | |
| if: "env.PRODUCTION == 'true'" | |
| with: | |
| github_token: ${{ secrets.GITHUB_TOKEN }} | |
| expire_strategy: 1 | |
| artifact_name: | | |
| js | |
| cs | |
| sdk | |
| gta | |
| - name: Purge older artifacts | |
| uses: Unnvaldr/actions-purge-artifacts@master | |
| if: "env.PRODUCTION == 'false'" | |
| with: | |
| github_token: ${{ secrets.GITHUB_TOKEN }} | |
| expire_strategy: 1 | |
| artifact_name: | | |
| nightly-js | |
| nightly-cs | |
| nightly-sdk | |
| nightly-gta |