Skip to content

Documentation

Documentation #1584

Workflow file for this run

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/github-actions-setvars@v0.1
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/github-actions-setvars@v0.1
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/release-downloader@v1.6
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/github-actions-setvars@v0.1
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/github-actions-setvars@v0.1
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/github-actions-setvars@v0.1
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/release-downloader@v1.6
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/release-downloader@v1.6
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/release-downloader@v1.6
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/release-downloader@v1.6
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/release-downloader@v1.6
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/release-downloader@v1.6
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