Skip to content

Commit aa6d4d5

Browse files
smailletsmaillet
authored
Docs Script/Tooling update (UbiquityDotNET#245)
* Added `Show-Docs.ps1` script to serve/host docs from local repo or another path. - Another path is useful for serving docs downloaded from GH actions before formal publication to ensure they are building correctly. * Added grey background to SVG images for dark theme to provide greater visibility of lines and drop shadows in parse diagrams.
1 parent f8036f0 commit aa6d4d5

File tree

4 files changed

+99
-51
lines changed

4 files changed

+99
-51
lines changed

‎Build-Docs.ps1

Lines changed: 30 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -16,28 +16,14 @@
1616
.PARAMETER ShowDocs
1717
Show the docs via `docfx serve --open-browser ...`. This option is useful for inner loop development of the docs as it allows
1818
opening a browser on the newly created docs for testing/checking the contents are produced correctly.
19-
20-
.PARAMETER ServeDocs
21-
Skips the docs build and implies ShowDocs to serve the current docs in the repo. This is useful after a previous
22-
Build-All or similar validation on a local machine as that will also build the docs but won't show/serve them.
2319
#>
2420
Param(
2521
[string]$Configuration="Release",
2622
[switch]$FullInit,
2723
[switch]$NoClone,
28-
[switch]$ShowDocs,
29-
[switch]$ServeDocs
24+
[switch]$ShowDocs
3025
)
3126

32-
function Invoke-DocFX
33-
{
34-
docfx $args
35-
if(!$?)
36-
{
37-
throw "Invoke of dotnet returned exit code: $LastExitCode"
38-
}
39-
}
40-
4127
function Get-FullBuildNumber
4228
{
4329
# docfx no longer supports the docfxconsole and insists on doing everything manually
@@ -78,54 +64,47 @@ try
7864
$docsOutputPath = $buildInfo['DocsOutputPath']
7965
Write-Information "Docs OutputPath: $docsOutputPath"
8066

81-
if(!$ServeDocs)
67+
# Clone docs output location so it is available as a destination for the Generated docs content
68+
# and the versioned docs links can function correctly for locally generated docs
69+
if(!$NoClone -and !(Test-Path (Join-Path $docsOutputPath '.git') -PathType Container))
8270
{
83-
# Clone docs output location so it is available as a destination for the Generated docs content
84-
# and the versioned docs links can function correctly for locally generated docs
85-
if(!$NoClone -and !(Test-Path (Join-Path $docsOutputPath '.git') -PathType Container))
71+
# clean out existing docs content so that clone can work
72+
if(Test-Path -PathType Container $docsOutputPath)
8673
{
87-
# clean out existing docs content so that clone can work
88-
if(Test-Path -PathType Container $docsOutputPath)
89-
{
90-
Write-Information "Cleaning $docsOutputPath"
91-
Remove-Item -Path $docsOutputPath -Recurse -Force -ProgressAction SilentlyContinue
92-
}
93-
94-
Write-Information "Cloning Docs repository"
95-
Invoke-External git clone $buildInfo['OfficialGitRemoteUrl'] -b gh-pages $docsOutputPath -q
74+
Write-Information "Cleaning $docsOutputPath"
75+
Remove-Item -Path $docsOutputPath -Recurse -Force -ProgressAction SilentlyContinue
9676
}
9777

98-
# Delete everything in the docs output except the git folder so the result of applying changes
99-
# is ONLY what is generated by this script.
100-
Write-Information "Cleaning $docsOutputPath"
101-
Get-ChildItem -Path $docsOutputPath -Exclude '.git' | remove-item -Recurse -Force -ProgressAction SilentlyContinue
78+
Write-Information "Cloning Docs repository"
79+
Invoke-External git clone $buildInfo['OfficialGitRemoteUrl'] -b gh-pages $docsOutputPath -q
80+
}
10281

103-
# Create a file to disable the default GitHub Pages use of JEKYLL as this uses docfx to generate the final
104-
# HTML. [It is at least theoretically plausible that JEKYLL could handle some/all of the metadata files produced
105-
# by DOCFX but it is not clear how much of the "build" stage would be lost if ONLY the metadata phase was used.
106-
# Thus, for now, this uses the docfx build phase.]
107-
"$([DateTime]::UtcNow.ToString('o'))" | Out-File -Path (Join-Path $docsOutputPath '.nojekyll')
82+
# Delete everything in the docs output except the git folder so the result of applying changes
83+
# is ONLY what is generated by this script.
84+
Write-Information "Cleaning $docsOutputPath"
85+
Get-ChildItem -Path $docsOutputPath -Exclude '.git' | remove-item -Recurse -Force -ProgressAction SilentlyContinue
10886

109-
$fullBuildNumber = Get-FullBuildNumber
110-
push-location './docfx'
111-
try
112-
{
113-
Write-Information "Building docs [FullBuildNumber=$fullBuildNumber]"
114-
Invoke-External docfx '-m' _buildVersion=$fullBuildNumber '-o' $docsOutputPath
115-
}
116-
finally
117-
{
118-
Pop-Location
119-
}
87+
# Create a file to disable the default GitHub Pages use of JEKYLL as this uses docfx to generate the final
88+
# HTML. [It is at least theoretically plausible that JEKYLL could handle some/all of the metadata files produced
89+
# by DOCFX but it is not clear how much of the "build" stage would be lost if ONLY the metadata phase was used.
90+
# Thus, for now, this uses the docfx build phase.]
91+
"$([DateTime]::UtcNow.ToString('o'))" | Out-File -Path (Join-Path $docsOutputPath '.nojekyll')
92+
93+
$fullBuildNumber = Get-FullBuildNumber
94+
push-location './docfx'
95+
try
96+
{
97+
Write-Information "Building docs [FullBuildNumber=$fullBuildNumber]"
98+
Invoke-External docfx '-m' _buildVersion=$fullBuildNumber '-o' $docsOutputPath
12099
}
121-
else
100+
finally
122101
{
123-
$ShowDocs = $true
102+
Pop-Location
124103
}
125104

126105
if($ShowDocs)
127106
{
128-
Invoke-External docfx serve '--open-browser' $docsOutputPath
107+
.\Show-Docs.ps1 $buildInfo
129108
}
130109
}
131110
catch

‎Show-Docs.ps1

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
<#
2+
.SYNOPSIS
3+
Shows docs using the docfx built-in server
4+
5+
.PARAMETER DocsPathToHost
6+
Path of docs to host. Default is the local build but any legit path is accepted.
7+
This is useful when downloading docs build artifacts to ensure they are built correctly.
8+
9+
.PARAMETER buildInfo
10+
BuildInfo to use for current repo build. The hashtable provided for this must include the
11+
`DocsOutputPath` value for the path to use. This is normally set by a call to `Initialize-Environment`
12+
#>
13+
Param(
14+
[Parameter(Mandatory, ParameterSetName = 'UsePath', Position = 0)]
15+
[string]$DocsPathToHost,
16+
17+
[Parameter(Mandatory, ParameterSetName = 'UseRepo', Position = 0)]
18+
[hashtable]$buildInfo
19+
)
20+
21+
$docFXToolVersion = '2.78.3'
22+
23+
$InformationPreference = 'Continue'
24+
$ErrorInformationPreference = 'Stop'
25+
26+
Push-Location $PSScriptRoot
27+
$oldPath = $env:Path
28+
try
29+
{
30+
. ./repo-buildutils.ps1
31+
32+
if ($PSCmdlet.ParameterSetName -eq 'UseRepo')
33+
{
34+
$DocsPathToHost = $buildInfo['DocsOutputPath']
35+
}
36+
37+
if (!(Test-Path $DocsPathToHost -PathType Container))
38+
{
39+
throw "Path '$DocsPathToHost' does not exist or is not a directory"
40+
}
41+
42+
# make sure the supported tool is installed.
43+
Invoke-External dotnet tool install --global docfx --version $docFXToolVersion | Out-Null
44+
Invoke-External docfx serve '--open-browser' $DocsPathToHost
45+
}
46+
catch
47+
{
48+
# Everything from the official docs to the various articles in the blog-sphere says this isn't needed
49+
# and in fact it is redundant - They're all WRONG! By re-throwing the exception the original location
50+
# information is retained and the error reported will include the correct source file and line number
51+
# data for the error. Without this, only the error message is retained and the location information is
52+
# Line 1, Column 1, of the outer most script file, which is, of course, completely useless.
53+
throw
54+
}
55+
finally
56+
{
57+
Pop-Location
58+
$env:Path = $oldPath
59+
}

‎docfx/templates/Ubiquity/public/main.css

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
@charset "UTF-8";
2+
23
/*
34
Customized Highlight JS theming
45
The default theming that comes with docfx 'modern' support is rather limited. It doesn't
@@ -68,6 +69,14 @@ code.hljs {
6869
font-weight: 700
6970
}
7071

72+
/*
73+
For the dark theme, set the background of SVG images to allow better
74+
visibility of thin lines and drop shadows etc...
75+
*/
76+
[data-bs-theme=dark] img,svg {
77+
background-color: grey
78+
}
79+
7180
[data-bs-theme=dark] pre code.hljs {
7281
display: block;
7382
overflow-x: auto;

‎src/Ubiquity.NET.Llvm.slnx

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@
3131
<File Path="../Push-Docs.ps1" />
3232
<File Path="../README.md" />
3333
<File Path="../repo-buildutils.ps1" />
34+
<File Path="../Show-Docs.ps1" />
3435
<File Path="../stylecop.json" />
3536
<File Path="x64.runsettings" />
3637
</Folder>

0 commit comments

Comments
 (0)