Automate deployment of generated docs

Author: natemcmaster

.appveyor.yml

@@ -9,8 +9,12 @@ branches:
     - /^feature\/.*/
 build_script:
   - ps: .\build.ps1 -IsOfficialBuild
-  - ps: .\docs\generate.ps1
+  - ps: .\docs\generate.ps1 -NoBuild
+on_success:
+  - ps: .\docs\push.ps1 -AppVeyor
 environment:
+  access_token:
+    secure: 7gza5cyC0Fwp5LcFPz9dGMcHXP2jxbrnu7er9R/HkdvnhzGJVADvOtfYO7+Vow5p
   global:
     DOTNET_SKIP_FIRST_TIME_EXPERIENCE: true
     DOTNET_CLI_TELEMETRY_OPTOUT: 1
@@ -30,3 +34,13 @@ deploy:
       branch: master
     api_key:
       secure: KF1yGk4IHJyyfiHfFSCxJ+p5iZX+KPfCTnCihjD5iIZjasTS1lHeilpbaon4wvcM
+  - provider: GitHub
+    description: 'See https://github.com/natemcmaster/CommandLineUtils/blob/master/CHANGELOG.md for details'
+    auth_token:
+      secure: 7gza5cyC0Fwp5LcFPz9dGMcHXP2jxbrnu7er9R/HkdvnhzGJVADvOtfYO7+Vow5p
+    artifact: Packages
+    draft: false
+    prerelease: false
+    on:
+      branch: master                 # release from master branch only
+      appveyor_repo_tag: true        # deploy on tag push only

build.ps1

@@ -12,16 +12,7 @@ param(
 Set-StrictMode -Version 1
 $ErrorActionPreference = 'Stop'
 
-function exec([string]$_cmd) {
-    write-host -ForegroundColor DarkGray ">>> $_cmd $args"
-    $ErrorActionPreference = 'Continue'
-    & $_cmd @args
-    $ErrorActionPreference = 'Stop'
-    if ($LASTEXITCODE -ne 0) {
-        write-error "Failed with exit code $LASTEXITCODE"
-        exit 1
-    }
-}
+Import-Module -Force -Scope Local "$PSScriptRoot/src/common.psm1"
 
 #
 # Main

docs/README.md

@@ -0,0 +1,3 @@
+Looking to read docs? Visit https://natemcmaster.github.io/CommandLineUtils/
+
+Looking to help write docs? Checkout [CONTRIBUTING.md](../CONTRIBUTING.md)

docs/docfx.json

@@ -37,7 +37,8 @@
         ],
         "exclude": [
           "**/obj/**",
-          "**.meta"
+          "**.meta",
+          "README.md"
         ]
       }
     ],

docs/generate.ps1

@@ -6,6 +6,8 @@ param(
 $ErrorActionPreference = 'Stop'
 Set-StrictMode -Version 2
 
+Import-Module -Force -Scope Local "$PSScriptRoot/src/common.psm1"
+
 Push-Location "$PSScriptRoot/../"
 
 try {
@@ -15,6 +17,7 @@ try {
     New-Item -ItemType Directory $buildRoot -ErrorAction Ignore
 
     if (-not (git worktree list --porcelain | Select-String 'gh-pages')) {
+        & git fetch origin gh-pages
         & git worktree add $targetDir gh-pages
     }
 
@@ -30,24 +33,24 @@ try {
     }
 
     Push-Location $targetDir
-    git rm --quiet --force -r .
+    & git rm --quiet --force -r .
     Pop-Location
 
     if (-not $NoBuild) {
-        & dotnet build -c Release
+        exec dotnet build -c Release
     }
 
     $arguments = @()
     try {
         if ($Serve) {
             $arguments += '--serve'
         }
-        & $docfx docs/docfx.json @arguments
+        exec $docfx docs/docfx.json @arguments
     }
     finally {
         Push-Location $targetDir
-        git add ./
-        git --no-pager status -s
+        & git add ./
+        & git --no-pager status -s
         Pop-Location
     }
 }

docs/push.ps1

@@ -0,0 +1,35 @@
+#requires -version 5
+param(
+    [string]$SourceCommit,
+    [switch]$DryRun,
+    [switch]$AppVeyor
+)
+
+$ErrorActionPreference = 'Stop'
+Set-StrictMode -Version 2
+
+Import-Module -Force -Scope Local "$PSScriptRoot/../src/common.psm1"
+
+$workdir = "$PSScriptRoot/../.build/docs/gh-pages"
+Push-Location $workdir
+try {
+
+    if ($AppVeyor) {
+        exec git config --global credential.helper store
+        Add-Content "$HOME\.git-credentials" "https://$($env:access_token):[email protected]`n"
+        exec git config --global user.email $env:APPVEYOR_REPO_COMMIT_AUTHOR
+        exec git config --global user.name $env:APPVEYOR_REPO_COMMIT_AUTHOR_EMAIL
+        $SourceCommit = $env:APPVEYOR_REPO_COMMIT
+    }
+
+    if (-not $SourceCommit) {
+        Push-Location $PSScriptRoot
+        $SourceCommit = $(git rev-parse HEAD)
+        Pop-Location
+    }
+    exec git commit -m "Generate documentation from $SourceCommit"
+    exec git push --dry-run
+}
+finally {
+    Pop-Location
+}

src/common.psm1

@@ -0,0 +1,10 @@
+function exec([string]$_cmd) {
+    write-host -ForegroundColor DarkGray ">>> $_cmd $args"
+    $ErrorActionPreference = 'Continue'
+    & $_cmd @args
+    $ErrorActionPreference = 'Stop'
+    if ($LASTEXITCODE -ne 0) {
+        write-error "Failed with exit code $LASTEXITCODE"
+        exit 1
+    }
+}