|
| 1 | +using module "PSModules/CommonBuild/CommonBuild.psd1" |
| 2 | +using module "PSModules/RepoBuild/RepoBuild.psd1" |
| 3 | + |
| 4 | +<# |
| 5 | +.SYNOPSIS |
| 6 | + Builds the docs for this repository |
| 7 | +
|
| 8 | +.PARAMETER Configuration |
| 9 | + This sets the build configuration to use, default is "Release" though for inner loop development this may be set to "Debug" |
| 10 | +
|
| 11 | +.PARAMETER FullInit |
| 12 | + Performs a full initialization. A full initialization includes forcing a re-capture of the time stamp for local builds |
| 13 | + as well as writes details of the initialization to the information and verbose streams. |
| 14 | +
|
| 15 | +.PARAMETER NoClone |
| 16 | + Skip cloning of the docs repository. Useful for inner loop development where you only do the clone once when iterating on |
| 17 | + doc updates. |
| 18 | +
|
| 19 | +.PARAMETER ShowDocs |
| 20 | + Show the docs via `docfx serve --open-browser ...`. This option is useful for inner loop development of the docs as it allows |
| 21 | + opening a browser on the newly created docs for testing/checking the contents are produced correctly. |
| 22 | +#> |
| 23 | +Param( |
| 24 | + [string]$Configuration="Release", |
| 25 | + [switch]$FullInit, |
| 26 | + [switch]$NoClone, |
| 27 | + [switch]$ShowDocs |
| 28 | +) |
| 29 | + |
| 30 | +$docFXToolVersion = '2.78.3' |
| 31 | + |
| 32 | +$InformationPreference = 'Continue' |
| 33 | +$ErrorInformationPreference = 'Stop' |
| 34 | + |
| 35 | +Push-Location $PSScriptRoot |
| 36 | +$oldPath = $env:Path |
| 37 | +try |
| 38 | +{ |
| 39 | + $buildInfo = Initialize-BuildEnvironment -FullInit:$FullInit |
| 40 | + |
| 41 | + # make sure the supported tool is installed. |
| 42 | + Invoke-External dotnet tool install --global docfx --version $docFXToolVersion | Out-Null |
| 43 | + |
| 44 | + $docsOutputPath = $buildInfo['DocsOutputPath'] |
| 45 | + Write-Information "Docs OutputPath: $docsOutputPath" |
| 46 | + |
| 47 | + # Clone docs output location so it is available as a destination for the Generated docs content |
| 48 | + # and the versioned docs links can function correctly for locally generated docs |
| 49 | + if(!$NoClone -and !(Test-Path (Join-Path $docsOutputPath '.git') -PathType Container)) |
| 50 | + { |
| 51 | + # clean out existing docs content so that clone can work |
| 52 | + if(Test-Path -PathType Container $docsOutputPath) |
| 53 | + { |
| 54 | + Write-Information "Cleaning $docsOutputPath" |
| 55 | + Remove-Item -Path $docsOutputPath -Recurse -Force -ProgressAction SilentlyContinue |
| 56 | + } |
| 57 | + |
| 58 | + Write-Information "Cloning Docs repository" |
| 59 | + Invoke-External git clone $buildInfo['OfficialGitRemoteUrl'] -b gh-pages $docsOutputPath -q |
| 60 | + } |
| 61 | + |
| 62 | + # Delete everything in the docs output except the git folder so the result of applying changes |
| 63 | + # is ONLY what is generated by this script. |
| 64 | + Write-Information "Cleaning $docsOutputPath" |
| 65 | + Get-ChildItem -Path $docsOutputPath -Exclude '.git' | remove-item -Recurse -Force -ProgressAction SilentlyContinue |
| 66 | + |
| 67 | + # Create a file to disable the default GitHub Pages use of JEKYLL as this uses docfx to generate the final |
| 68 | + # HTML. [It is at least theoretically plausible that JEKYLL could handle some/all of the metadata files produced |
| 69 | + # by DOCFX but it is not clear how much of the "build" stage would be lost if ONLY the metadata phase was used. |
| 70 | + # Thus, for now, this uses the docfx build phase.] |
| 71 | + "$([DateTime]::UtcNow.ToString('o'))" | Out-File -Path (Join-Path $docsOutputPath '.nojekyll') |
| 72 | + |
| 73 | + $generatedVersionInfo = [xml](Get-Content (Join-Path $buildInfo['RepoRootPath'] 'GeneratedVersion.props')) |
| 74 | + $fullBuildNumber = $generatedVersionInfo.Project.PropertyGroup.InformationalVersion |
| 75 | + |
| 76 | + push-location './docfx' |
| 77 | + try |
| 78 | + { |
| 79 | + Write-Information "Building docs [FullBuildNumber=$fullBuildNumber]" |
| 80 | + Invoke-External docfx '-m' _buildVersion=$fullBuildNumber '-o' $docsOutputPath |
| 81 | + } |
| 82 | + finally |
| 83 | + { |
| 84 | + Pop-Location |
| 85 | + } |
| 86 | + |
| 87 | + if($ShowDocs) |
| 88 | + { |
| 89 | + .\Show-Docs.ps1 $buildInfo |
| 90 | + } |
| 91 | +} |
| 92 | +catch |
| 93 | +{ |
| 94 | + # Everything from the official docs to the various articles in the blog-sphere says this isn't needed |
| 95 | + # and in fact it is redundant - They're all WRONG! By re-throwing the exception the original location |
| 96 | + # information is retained and the error reported will include the correct source file and line number |
| 97 | + # data for the error. Without this, only the error message is retained and the location information is |
| 98 | + # Line 1, Column 1, of the outer most script file, which is, of course, completely useless. |
| 99 | + throw |
| 100 | +} |
| 101 | +finally |
| 102 | +{ |
| 103 | + Pop-Location |
| 104 | + $env:Path = $oldPath |
| 105 | +} |
0 commit comments