-
Notifications
You must be signed in to change notification settings - Fork 12
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Docs get built and published (to netlify) on commit. Also builds docs as a downloadable PDF. This is a combination of 6 commits. add first github actions workflow for docs building Adds CI actions for building and publishing docs Also adds a PDF variant of the docs Fixed a bug in the asset chooser html Reorganized a few sections Added a new `index` document type that will list all the pages in the current section after the conceptual content. Generalized the git version file so that it can output key-value, json, CI commands, or environment variables! Remove unnecessary gh docfx download limit choco logs Avoid nostdin dotnet/docfx#4488 wkhtmltopdf/wkhtmltopdf#4450 Add netlify auth token Fixes #315
- Loading branch information
Showing
40 changed files
with
819 additions
and
1,268 deletions.
There are no files selected for viewing
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,53 @@ | ||
| name: docs | ||
|
|
||
| on: | ||
| push: | ||
| branches: [ master ] | ||
| pull_request: | ||
| branches: [ master ] | ||
|
|
||
| jobs: | ||
| build-docs: | ||
|
|
||
| # docfx v2 is a .NET Framework project and only runs on Windows | ||
| runs-on: windows-latest | ||
|
|
||
| steps: | ||
| # checkout and cache lfs | ||
| - name: Checkout code | ||
| uses: actions/checkout@v2 | ||
| with: | ||
| fetch-depth: 100 | ||
|
|
||
| - name: Create LFS file list | ||
| run: git lfs ls-files -l | cut -d' ' -f1 | sort > .lfs-assets-id | ||
|
|
||
| - name: Restore LFS cache | ||
| uses: actions/cache@v2 | ||
| id: lfs-cache | ||
| with: | ||
| path: .git/lfs | ||
| key: ${{ runner.os }}-lfs-${{ hashFiles('.lfs-assets-id') }}-v1 | ||
|
|
||
| - name: Git LFS Pull | ||
| run: git lfs pull | ||
|
|
||
| # setup and build solution | ||
| # - name: Setup .NET | ||
| # uses: actions/setup-dotnet@v1 | ||
|
|
||
| # - name: Restore dependencies | ||
| # run: dotnet restore | ||
|
|
||
| # - name: Build | ||
| # run: dotnet build --no-restore | ||
|
|
||
| - name: Generate docs | ||
| shell: pwsh | ||
| run: ./build/generate_docs.ps1 | ||
|
|
||
| - name: Publish docs | ||
| shell: pwsh | ||
| env: | ||
| NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }} | ||
| run: ./build/publish_docs.ps1 |
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| [submodule "docs2/theme"] | ||
| path = docs2/theme | ||
| url = https://github.com/statiqdev/CleanBlog.git |
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
|
|
||
|
|
||
| function is_CI() { | ||
| $env:CI -eq "true" | ||
| } |
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| function script:exec { | ||
| [CmdletBinding()] | ||
|
|
||
| param( | ||
| [Parameter(Position = 0, Mandatory = 1)][scriptblock]$cmd, | ||
| [Parameter(Position = 1, Mandatory = 0)][string]$errorMessage, | ||
|
|
||
| [switch]$WhatIf = $false | ||
| ) | ||
| if ($WhatIf) { | ||
| $InformationPreference = 'Continue' | ||
| Write-Information "Would execute `"$cmd`"" | ||
| return; | ||
| } | ||
|
|
||
| & $cmd | ||
| if ($LASTEXITCODE -ne 0) { | ||
| throw ("Error ($LASTEXITCODE) executing command: {0}" -f $cmd) + ($errorMessage ?? "") | ||
| } | ||
| } |
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,40 +1,58 @@ | ||
| . $PSScriptRoot/exec.ps1 | ||
| . $PSScriptRoot/log.ps1 | ||
| $ErrorActionPreference = "Stop" | ||
|
|
||
| Push-Location | ||
|
|
||
| if ($null -eq (Get-Command docfx -ErrorAction SilentlyContinue)) { | ||
| Write-output "Installing docfx..." | ||
| #dotnet tool install -g docfx --version "3.0.0-*" --add-source https://www.myget.org/F/docfx-v3/api/v2 | ||
| choco install docfx -y | ||
| Set-Location "$PSScriptRoot/../" | ||
|
|
||
| } | ||
| try { | ||
| if ($null -eq (Get-Command docfx -ErrorAction SilentlyContinue)) { | ||
| log "Installing docfx..." "Install tools" | ||
| #dotnet tool install -g docfx --version "3.0.0-*" --add-source https://www.myget.org/F/docfx-v3/api/v2 | ||
| exec { choco install docfx wkhtmltopdf -y --limit-output --no-progress } | ||
| } | ||
|
|
||
| # if (-not ((docfx --version) -match "^3.0.*")) { | ||
| # Write-Error "We require docfx version 3" | ||
| # } | ||
| # if (-not ((docfx --version) -match "^3.0.*")) { | ||
| # Write-Error "We require docfx version 3" | ||
| # } | ||
|
|
||
| Write-Output "Extracting git version metadata" | ||
| . $PSScriptRoot/../src/git_version.ps1 | Split-String "`n", "`r" -RemoveEmptyStrings | ForEach-Object { $result = @{ } } { | ||
| $key, $value = $_ -split "=" | ||
| $result.Add("AP_$key", $value ) | ||
| } { $result } | ConvertTo-JSON | Out-File "$PSScriptRoot/../docs/apMetadata.json" | ||
| log "Extracting git version metadata" "Prepare metadata" | ||
| & $PSScriptRoot/../src/git_version.ps1 -json -prefix "AP_" > "$PSScriptRoot/../docs/apMetadata.json" | ||
| log "Extracting git version metadata (ENVIRONMENT VARIABLES)" | ||
| & $PSScriptRoot/../src/git_version.ps1 -env_vars -prefix "AP_" | set-content | ||
|
|
||
| Set-Location docs | ||
|
|
||
| log "[Disabled] Prepare API metadata for docs" | ||
| # metadata generation disabled due to a StackOverflowException that occurs | ||
| # if we try to build the docs after a metadata generation has been done | ||
| #exec { docfx metadata } | ||
|
|
||
| log "Building pdf docs" "Build PDF" | ||
| exec { docfx pdf --log verbose } | ||
|
|
||
| try { | ||
| Write-Output "Startign docs build" | ||
| Push-Location | ||
| Set-Location docs | ||
| log "moving pdf" "PDF" | ||
| $pdf_name = "ap_manual_${Env:AP_Version}.pdf" | ||
| Move-Item "ap_manual_pdf.pdf" $pdf_name -Force | ||
|
|
||
| docfx metadata | ||
| log "generating pdf xref files" | ||
| $xref_content = @" | ||
| {"references":[{"uid":"invariant_ap_manual_ref","name":"Download AP PDF","href":"$pdf_name","fullName":"PDF Download for AP.exe docs version ${Env:AP_Version}"}]} | ||
| "@ | ||
| Set-Content -Encoding utf8NoBOM -Path "pdf_xrefmap.yml" -Value $xref_content | ||
|
|
||
| docfx build --log verbose | ||
|
|
||
| log "Building docs" "Build docs" | ||
| exec { docfx build --log verbose } | ||
|
|
||
| if ($LASTEXITCODE -ne 0) { | ||
| Write-Error "Failed to build docs, skipping deploy" | ||
| exit 1 | ||
| } | ||
| log "✅ Doc generation success" | ||
| } | ||
| catch { | ||
| Write-Output $_ | ||
| Write-Error "Failed to build docs." | ||
| } | ||
| finally { | ||
| Pop-Location | ||
| finish_log | ||
| } |
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,47 @@ | ||
| #Requires -Version 7 | ||
|
|
||
| . $PSScriptRoot/ci.ps1 | ||
|
|
||
| $script:current_section = $null | ||
|
|
||
| function script:log { | ||
| [CmdletBinding()] | ||
|
|
||
| param( | ||
| [Parameter(Position = 0, Mandatory = 1)][string]$message, | ||
| [Parameter(Position = 1, Mandatory = 0)][string]$section = "" | ||
| ) | ||
|
|
||
|
|
||
| # $null - reset group | ||
| # "" - maintain group | ||
| # * - anything else, new group | ||
| if ($section -ne "") { | ||
| # reset group | ||
| if ((is_CI) -and $null -ne $script:current_section) { | ||
| Write-Output "::endgroup::" | ||
| } | ||
|
|
||
| # update state | ||
| $script:current_section = $section | ||
|
|
||
| # if starting a new group | ||
| if ($null -ne $section -and (is_CI)) { | ||
| # emit new section | ||
| Write-Output "::group::$script:current_section" | ||
| } | ||
| } | ||
|
|
||
| $tag = $null -ne $script:current_section ? "[$script:current_section] " : "" | ||
| Write-Output "${tag}$message" | ||
| } | ||
|
|
||
| function script:finish_log { | ||
| [CmdletBinding()] | ||
| param() | ||
|
|
||
| $script:current_section = $null | ||
| if ((is_CI)) { | ||
| Write-Output "::endgroup::" | ||
| } | ||
| } |
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
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
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -7,5 +7,5 @@ | |
| "recognisers", | ||
| "recognizers", | ||
| "visualise" | ||
| ], | ||
| ] | ||
| } | ||
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
Oops, something went wrong.