Improve tools/ci/build-docs.ps1 [skip ci]

Author: halx99

.gitignore

@@ -202,7 +202,7 @@ temp/
 **/SharedLoader.java
 
 # ignore downloaded tools
-tools/external/
+tools/external
 
 # ignore lua-tests res folder which is copy from cpp-tests
 tests/lua-tests/res/

docs/menu_version.js.in

@@ -2,7 +2,7 @@
   'use strict';
 
   var url_re =  /(axmol\.dev\/manual\/)(latest|(\d\.\d+|\d\.\d+\.\d+)(-beta\d)?)\//;
-  var url_local =  /dist\/site1\/manual\/(latest|(\d\.\d+|\d\.\d+\.\d+)(-beta\d)?)\//;
+  var url_local =  /dist\/manual\/(latest|(\d\.\d+|\d\.\d+\.\d+)(-beta\d)?)\//;
   var current_version_local = '@VERSION@'
   var all_versions = [
       @VERLIST@
@@ -43,7 +43,7 @@
       return url.replace(url_re, 'axmol.dev/manual/' + new_version + '/');
     }
     else {
-      return url.replace(url_local, 'dist/site1/manual/' + new_version + '/');
+      return url.replace(url_local, 'dist/manual/' + new_version + '/');
     }
   }
 

tools/ci/build-docs.ps1

@@ -7,6 +7,8 @@ param(
 
 $myRoot = $PSScriptRoot
 
+$ErrorActionPreference = 'Stop'
+
 $isWin = $IsWindows -or ("$env:OS" -eq 'Windows_NT')
 
 $pwsh_ver = $PSVersionTable.PSVersion.ToString()
@@ -18,8 +20,6 @@ if (!$git_prog) {
     throw 'build-docs: requires git installed'
 }
 
-$stored_branch = $(git -C $AX_ROOT branch --show-current)
-
 function mkdirs([string]$path) {
     if (!(Test-Path $path)) {
         New-Item $path -ItemType Directory 1>$null
@@ -88,25 +88,35 @@ setup_doxygen
 
 Write-Host "Using doxygen $(doxygen --version)"
 
-$remote_default_branch = (git symbolic-ref refs/remotes/origin/HEAD) -replace '^refs/remotes/origin/', ''
-$latest_branch = $remote_default_branch
+# begin generate docs
 
-Write-Host "remote_default_branch=$remote_default_branch"
+$latest_branch = $(git -C $AX_ROOT branch --show-current)
+if (!$latest_branch) {
+    throw "please checkout a branch as latest doc version"
+}
+
+$remote_default_branch = (git symbolic-ref refs/remotes/origin/HEAD) -replace '^refs/remotes/origin/', ''
+Write-Host "latest_branch=$latest_branch, remote_default_branch=$remote_default_branch"
 
-function parse_latest_rev() {
-    git checkout $latest_branch | Out-Host
-    $axver_file = (Resolve-Path $AX_ROOT/axmol/axmolver.h.in).Path
+# parse revision of current head ref to x.y.z-beef123
+function parse_current_rev() {
+    $axver_file = Join-Path $AX_ROOT 'axmol/axmolver.h.in'
+    if (!(Test-Path $axver_file -PathType Leaf)) {
+        $axver_file = (Resolve-Path $AX_ROOT/core/axmolver.h.in).Path
+    }
     $axver_content = $(Get-Content -Path $axver_file)
-    function parse_axver($part) {
+
+    $parse_axver = {
+        param($part)
         return ($axver_content | Select-String "#define AX_VERSION_$part").Line.Split(' ')[2]
     }
 
-    $axver = "$(parse_axver 'MAJOR').$(parse_axver 'MINOR').$(parse_axver 'PATCH')"
+    $axver = "$(&$parse_axver 'MAJOR').$(&$parse_axver 'MINOR').$(&$parse_axver 'PATCH')"
 
-    $branchName = $(git -C $AX_ROOT branch --show-current)
-    if ($branchName.StartsWith('dev/')) {
-        $commitHash = $(git -C $AX_ROOT rev-parse --short=7 HEAD)
-        $axver += "-$commitHash"
+    $branch_name = $(git -C $AX_ROOT branch --show-current)
+    if ($branch_name.StartsWith('dev/') -or $branch_name.StartsWith('release/')) {
+        $short_sha = $(git -C $AX_ROOT rev-parse --short=7 HEAD)
+        $axver += "-$short_sha"
     }
     return $axver
 }
@@ -130,63 +140,86 @@ function  configure_file($infile, $outfile, $vars) {
 
 # build manuals
 
-# query version map to build docs
+# collection ver_list
+# doc_ver   2.4         latest
+# ref       v2.4.1      dev/v3
+# 
 $release_tags = $(git tag)
-$verMap = @{}
+$ver_list = [System.Collections.ArrayList]::new()
+
+$ver_list.Add([PSCustomObject]@{
+        doc_ver  = 'latest'
+        head_ref = $latest_branch
+    }) | Out-Null
+
 foreach ($item in $release_tags) {
     if ([Regex]::Match($item, '^v[0-9]+\.[0-9]+\.[0-9]+$').Success) {
-        $docVer = $($item.Split('.')[0..1] -join '.').TrimStart('v')
-        if ($docVer -lt $min_ver) {
+        $doc_ver = $($item.Split('.')[0..1] -join '.').TrimStart('v')
+        if ($doc_ver -lt $min_ver) {
             continue
         }
-        $verMap[$docVer] = $item
+        $ver_list.Add([PSCustomObject]@{
+                doc_ver  = $doc_ver
+                head_ref = $item
+            }) | Out-Null
     }
 }
 
-$verList = $verMap.GetEnumerator() | Sort-Object Value -Descending | ForEach-Object { $_.Key }
-
-$verMap['latest'] = parse_latest_rev
+$ver_list.Sort([System.Collections.Generic.Comparer[object]]::Create({
+            param($x, $y)
+            return [System.Collections.Comparer]::Default.Compare($y.doc_ver, $x.doc_ver)
+        }))
+$ver_list | Format-Table doc_ver, head_ref -AutoSize
 
-$strVerList = "'latest','$($verList -join "','")'"
-Write-Host "$(Out-String -InputObject $verMap)"
+$menu_ver_list = ($ver_list | ForEach-Object { "'$($_.doc_ver)'" }) -join ','
 
 # set default doc ver to 'latest'
 mkdirs "$site_dist/manual"
 configure_file './doc_index.html.in' "$site_dist/manual/index.html" @{'@VERSION@' = 'latest' }
 
-$branches = $(git branch -a)
-$canon_branches = @{}
-foreach ($branch in $branches) {
-    $canon_branches[$branch.Trim()] = $true
-}
+function generate_docs($ver_info) {
+    $doc_ver = $ver_info.doc_ver
+    $head_ref = $ver_info.head_ref
 
-# build manuals
-foreach ($item in $verMap.GetEnumerator()) {
-    $ver = $item.Key
-    $release_tag = $item.Value
-    Write-Host "Generating docs for ${ver}:${release_tag} ..."
+    # checkout
+    Write-Host "Checking out to ${doc_ver}:${head_ref} ..."
+    git checkout "$head_ref" --force | Out-Host
+    $current_ref = git symbolic-ref --short HEAD 2>/dev/null || git describe --tags --exact-match 2>/dev/null
+    if ($current_ref -ne $head_ref -and $LASTEXITCODE -ne 0) {
+        throw "git checkout `"$head_ref`" failed or did not switch HEAD"
+    }
+    if ($doc_ver -eq 'latest') {
+        $real_ver = parse_current_rev
+    }
+    else {
+        $real_ver = $head_ref
+    }
 
-    $html_out = Join-Path $site_dist "manual/$ver"
-    mkdirs $html_out
+    Write-Host "Generating docs for ${doc_ver}:${head_ref} ..."
 
-    if($ver -ne 'latest') {
-        git checkout $release_tag | Out-Host
-    } else {
-        git checkout $latest_branch | Out-Host
-    }
+    # prepare html_out
+    $html_out = Join-Path $site_dist "manual/$doc_ver"
+    mkdirs $html_out
 
-    configure_file './Doxyfile.in' './Doxyfile' @{'@VERSION@' = $release_tag; '@OUTPUT_DIR@' = $site_dist; './dist' = $site_dist; '@HTML_OUTPUT@' = "manual/$ver" }
+    # configure file
+    configure_file './Doxyfile.in' './Doxyfile' @{'@VERSION@' = $real_ver; '@OUTPUT_DIR@' = $site_dist; './dist' = $site_dist; '@HTML_OUTPUT@' = "manual/$doc_ver" }
 
+    # generate docs
     doxygen "./Doxyfile" # 1>$null 2>$null
 
     Copy-Item './hacks.js' $html_out
     Copy-Item './doc_style.css' "$html_out/stylesheet.css"
-    configure_file './menu_version.js.in' "$html_out/menu_version.js" @{'@VERLIST@' = $strVerList; '@VERSION@' = $ver }
+    configure_file './menu_version.js.in' "$html_out/menu_version.js" @{'@VERLIST@' = $menu_ver_list; '@VERSION@' = $doc_ver }
 
-    Write-Host "Generating docs for ${ver}:${release_tag} done"
+    Write-Host "Generating docs for ${doc_ver}:${real_ver} done"
+}
+
+# build manuals
+foreach ($ver in $ver_list) {
+    generate_docs $ver
 }
 
-# checkout back to stored branch
-git checkout $stored_branch
+# checkout back to latest branch
+git checkout $latest_branch
 
 Set-Location $store_cwd