Added build documentation support.

.github/workflows/release-build.yml

@@ -27,6 +27,14 @@ jobs:
       - name: Build Source
         run: .\Build-All.ps1
 
+      - name: Run Tests
+        run: ./Invoke-Tests.ps1
+
+      - name: Publish Test Results
+        uses: EnricoMi/publish-unit-test-result-action/windows@v2
+        with:
+          files: BuildOutput/Test-Results/*.trx
+
       - name: Publish Artifacts
         uses: actions/upload-artifact@v4
         with:
@@ -36,11 +44,23 @@ jobs:
       - name: Show asset names
         run: dir BuildOutput/Nuget
 
+      - name: Commit Docs
+        env:
+          docspush_email: [email protected]
+          docspush_username: cibuild-telliam
+        run: .\Push-Docs.ps1 -SkipPush
+
+      - name: Push Docs
+        uses: ad-m/github-push-action@master
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          directory: .\BuildOutput\docs
+          branch: gh-pages
+
       - name: Publish packages to NuGet.org
         run: dir .\BuildOutput\NuGet\*.nupkg | .\Push-Nuget.ps1 -apiKey ${{ secrets.NUGETPUSH_ACCESS_TOKEN }}
 
       - name: Create Release
-        id: create_release
         uses: softprops/action-gh-release@v2
         with:
           tag_name: ${{ github.ref }}

Build-Docs.ps1

@@ -0,0 +1,105 @@
+using module "PSModules/CommonBuild/CommonBuild.psd1"
+using module "PSModules/RepoBuild/RepoBuild.psd1"
+
+<#
+.SYNOPSIS
+    Builds the docs for this repository
+
+.PARAMETER Configuration
+    This sets the build configuration to use, default is "Release" though for inner loop development this may be set to "Debug"
+
+.PARAMETER FullInit
+    Performs a full initialization. A full initialization includes forcing a re-capture of the time stamp for local builds
+    as well as writes details of the initialization to the information and verbose streams.
+
+.PARAMETER NoClone
+    Skip cloning of the docs repository. Useful for inner loop development where you only do the clone once when iterating on
+    doc updates.
+
+.PARAMETER ShowDocs
+    Show the docs via `docfx serve --open-browser ...`. This option is useful for inner loop development of the docs as it allows
+    opening a browser on the newly created docs for testing/checking the contents are produced correctly.
+#>
+Param(
+    [string]$Configuration="Release",
+    [switch]$FullInit,
+    [switch]$NoClone,
+    [switch]$ShowDocs
+)
+
+$docFXToolVersion = '2.78.3'
+
+$InformationPreference = 'Continue'
+$ErrorInformationPreference = 'Stop'
+
+Push-Location $PSScriptRoot
+$oldPath = $env:Path
+try
+{
+    $buildInfo = Initialize-BuildEnvironment -FullInit:$FullInit
+
+    # make sure the supported tool is installed.
+    Invoke-External dotnet tool install --global docfx --version $docFXToolVersion | Out-Null
+
+    $docsOutputPath = $buildInfo['DocsOutputPath']
+    Write-Information "Docs OutputPath: $docsOutputPath"
+
+    # Clone docs output location so it is available as a destination for the Generated docs content
+    # and the versioned docs links can function correctly for locally generated docs
+    if(!$NoClone -and !(Test-Path (Join-Path $docsOutputPath '.git') -PathType Container))
+    {
+        # clean out existing docs content so that clone can work
+        if(Test-Path -PathType Container $docsOutputPath)
+        {
+            Write-Information "Cleaning $docsOutputPath"
+            Remove-Item -Path $docsOutputPath -Recurse -Force -ProgressAction SilentlyContinue
+        }
+
+        Write-Information "Cloning Docs repository"
+        Invoke-External git clone $buildInfo['OfficialGitRemoteUrl'] -b gh-pages $docsOutputPath -q
+    }
+
+    # Delete everything in the docs output except the git folder so the result of applying changes
+    # is ONLY what is generated by this script.
+    Write-Information "Cleaning $docsOutputPath"
+    Get-ChildItem -Path $docsOutputPath -Exclude '.git' | remove-item -Recurse -Force -ProgressAction SilentlyContinue
+
+    # Create a file to disable the default GitHub Pages use of JEKYLL as this uses docfx to generate the final
+    # HTML. [It is at least theoretically plausible that JEKYLL could handle some/all of the metadata files produced
+    # by DOCFX but it is not clear how much of the "build" stage would be lost if ONLY the metadata phase was used.
+    # Thus, for now, this uses the docfx build phase.]
+    "$([DateTime]::UtcNow.ToString('o'))" | Out-File -Path (Join-Path $docsOutputPath '.nojekyll')
+
+    $generatedVersionInfo = [xml](Get-Content (Join-Path $buildInfo['RepoRootPath'] 'GeneratedVersion.props'))
+    $fullBuildNumber = $generatedVersionInfo.Project.PropertyGroup.InformationalVersion
+
+    push-location './docfx'
+    try
+    {
+        Write-Information "Building docs [FullBuildNumber=$fullBuildNumber]"
+        Invoke-External docfx '-m' _buildVersion=$fullBuildNumber '-o' $docsOutputPath
+    }
+    finally
+    {
+        Pop-Location
+    }
+
+    if($ShowDocs)
+    {
+        .\Show-Docs.ps1 $buildInfo
+    }
+}
+catch
+{
+    # Everything from the official docs to the various articles in the blog-sphere says this isn't needed
+    # and in fact it is redundant - They're all WRONG! By re-throwing the exception the original location
+    # information is retained and the error reported will include the correct source file and line number
+    # data for the error. Without this, only the error message is retained and the location information is
+    # Line 1, Column 1, of the outer most script file, which is, of course, completely useless.
+    throw
+}
+finally
+{
+    Pop-Location
+    $env:Path = $oldPath
+}

Directory.Build.props

@@ -1,6 +1,6 @@
 <Project>
     <!--
-    For local builds of this project in IDE ONLY
+    For local builds of this solution in IDE ONLY
     FORCE the Build Versioning Info as there is no lib to rely on; (This repo builds it!) and the automated build
     scripts aren't used to build from within an IDE. Automated builds/Command line builds use the PowerShell
     scripts to setup the variables for use in the build. This, handles the case of builds directly from the IDE
@@ -11,6 +11,7 @@
     -->
     <PropertyGroup Condition="'$(BuildingInsideVisualStudio)'=='true'">
         <!-- File Version for v5.0.0-alpha (See: https://csemver.org/playground/site/#/) [1.27597.27630.61954]-->
+        <!-- CiBuildIndex => UInt16.MaxValue -->
         <!-- +1 to revision to account for CI build -->
         <FileVersion>1.27597.27630.61955</FileVersion>
         <PackageVersion>5.0.0-a.ci-4294967295.IDE</PackageVersion>
@@ -19,7 +20,11 @@
         <InformationalVersion>$(ProductVersion)</InformationalVersion>
     </PropertyGroup>
 
-    <Import Condition="'$(BuildingInsideVisualStudio)'!='true'" Project="GeneratedVersion.props" />
+    <!--
+    For command line builds (including official PR/CI/Release automated builds) use the props file
+    generated by the scripts.
+    -->
+    <Import Condition="'$(BuildingInsideVisualStudio)'!='true' AND '$(MSBuildProjectExtension)'!='.pssproj'" Project="GeneratedVersion.props" />
 
     <!--
     Description:

Directory.Build.targets

@@ -4,22 +4,26 @@
     </Target>
 
     <Target Name="ShowBuildParameters">
+        <Message Importance="normal" Text="Build paths:" />
         <Message Importance="normal" Text="              BuildRootDir: $(BuildRootDir)" />
         <Message Importance="normal" Text="       BaseBuildOutputPath: $(BaseBuildOutputPath)" />
         <Message Importance="normal" Text="    BaseBuildOutputBinPath: $(BaseBuildOutputBinPath)" />
         <Message Importance="normal" Text="BaseIntermediateOutputPath: $(BaseIntermediateOutputPath)" />
         <Message Importance="normal" Text="                    IntDir: $(IntDir)" />
         <Message Importance="normal" Text="            BaseOutputPath: $(BaseOutputPath)" />
+        <Message Importance="normal" Text="Versioning:" />
         <Message Importance="normal" Text="           FullBuildNumber: $(FullBuildNumber)"/>
         <Message Importance="normal" Text="            PackageVersion: $(PackageVersion)"/>
         <Message Importance="normal" Text="               FileVersion: $(FileVersion)"/>
+        <Message Importance="normal" Text="           AssemblyVersion: $(AssemblyVersion)"/>
+        <Message Importance="normal" Text="      InformationalVersion: $(InformationalVersion)"/>
         <Message Importance="normal" Text="                  Platform: $(Platform)"/>
         <Message Importance="normal" Text="             Configuration: $(Configuration)"/>
     </Target>
 
     <Target Name="VerifyProjectSettings" Condition="'$(MSBuildProjectExtension)'=='.csproj'">
         <!--
-        Detect if something has this horrible non-feature enabled. It is a blight on the build/language that should never have been added
+        Detect if something has this horrible non-feature enabled. It is a blight on the build that should never have been added,
         let alone used as the default for projects with no way to block/disable it all up...
 
         NOTE:
@@ -36,6 +40,6 @@
         -->
         <Error Condition="'$(ImplicitUsings)'!='disable'" Text="$(MSBuildProjectFile) - Projects in this repository MUST NOT have ImplicitUsings enabled!"/>
 
-        <Warning Condition="'$(BuildingInsideVisualStudio)' == 'true'" Text="!!! This is an IDE build-Version numbering is 'FAKED' !!!"/>
+        <Warning Condition="'$(BuildingInsideVisualStudio)' == 'true'" Text="!!! This is an IDE build. Version numbering is 'FAKED' !!!"/>
     </Target>
 </Project>

Directory.Packages.props

@@ -5,12 +5,9 @@
   -->
   <ItemGroup>
     <!--
-        While some aspects of this analyzer are helpful, it hasn't been without issues. Worse, the last non-preview release
-        was Apr of 2019, That's a LONG time ago. Even the most recent preview (beta) was back in Dec. of 2023. So not much
-        sign of life/activity nor hope of updates to bug fixes. It's sad to see this go as relying on a developer/reviewers
-        to follow the rules is a recipe for failures. Automation is how that works. (With occasional overrides that should
-        get the attention of a reviewer).
-        -->
+    NOTE: This analyzer is sadly, perpetually in "pre-release mode". There have been many issues/discussion on the point
+    and it has all fallen on deaf ears. So policies regarding "NO-Prerelease" components need to be overruled on this one
+    -->
     <GlobalPackageReference Include="StyleCop.Analyzers" Version="1.2.0-beta.556" Condition="'$(UseStyleCop)' != 'false'" />
   </ItemGroup>
   <!--
@@ -27,4 +24,4 @@
     <PackageVersion Include="MSTest.TestFramework" Version="3.9.1" />
     <PackageVersion Include="Polyfill" Version="7.31.0" />
   </ItemGroup>
-</Project>
+</Project>

IgnoredWords.dic

@@ -0,0 +1,140 @@
+ABI
+Accessor
+Addr
+alloca
+anonymize
+antlr
+api
+app
+apps
+argkind
+ascii
+atomicrmw
+attrib
+Attribs
+AttributeSet
+Attrs
+baz
+binaryop
+binlogs
+binop
+bitcode
+Blinky
+blittable
+blockdiag
+blog
+bool
+buildbinoutput
+buildtransitive
+builtinop
+byref
+byval
+castable
+cibuild
+Cmp
+Comdat
+Comdats
+compat
+Concat
+Config
+const
+contentfiles
+Contributors
+crlf
+csharp
+csproj
+de
+defacto
+dllimport
+docfx
+docfxconsole
+dotnet
+endianess
+enum
+Enums
+env
+exe
+facepalm
+finalizers
+foo
+fullsrc
+func
+getelementptr
+gh
+github
+Globalization
+Hashtable
+Identifier
+Impl
+inline
+inlined
+Interop
+jit
+Lexer
+LValue
+malloc
+marshallers
+marshalling
+memcopy
+metadata
+Mips
+msbuild
+msg
+nav
+nint
+noinline
+nounwind
+nuint
+nullability
+Nullable
+optimizenone
+pages
+paren
+perf
+pointee
+Pre
+proj
+readonly
+refactor
+refcount
+repl
+repo
+RMW
+runtimes
+RValue
+sizeof
+src
+Stateful
+struct
+structs
+Subrange
+Sym
+telliam
+tl
+trx
+typdef
+Typedef
+typeof
+uid
+uint
+unaryop
+Undefine
+undiscoverable
+Unhandled
+uniqued
+uniqueing
+unmarshal
+userdefinedop
+Users
+usings
+utils
+variadic
+vcxproj
+versioned
+versioning
+Xchg
+Xor
+xref
+xxx
+yaml
+yyyy