Made previous release docs available

Build-Docs.ps1

@@ -1,7 +1,7 @@
 Param(
     [string]$Configuration="Release",
     [switch]$AllowVsPreReleases,
-    [switch]$NoClone = (!([System.Convert]::ToBoolean($env:IsAutomatedBuild)))
+    [switch]$NoClone
 )
 
 pushd $PSScriptRoot
@@ -15,34 +15,37 @@ try
                             LlvmVersion = $buildInfo['LlvmVersion']
                           }
 
+    $docsOutputPath = $buildInfo['DocsOutputPath']
     # clone docs output location so it is available as a destination for the Generated docs content
-    if(!$NoClone -and !(Test-Path (Join-Path $buildInfo['DocsOutputPath'] '.git') -PathType Container))
+    # and the versioned docs links can function correctly for locally generated docs
+    if(!$NoClone -and !(Test-Path (Join-Path $docsOutputPath '.git') -PathType Container))
     {
-        Write-Information "Cloning Docs repository"
-        pushd BuildOutput -ErrorAction Stop
-        try
+        if(Test-Path -PathType Container $docsOutputPath)
         {
-            git clone https://github.com/UbiquityDotNET/Llvm.NET.git -b gh-pages docs -q
-            if( !$? )
-            {
-                throw "Git clone failed"
-            }
+            del -Path $docsOutputPath -Recurse -Force
         }
-        finally
+
+        Write-Information "Cloning Docs repository"
+        git clone https://github.com/UbiquityDotNET/Llvm.NET.git -b gh-pages $docsOutputPath -q
+        if(!$?)
         {
-            popd
+            throw "Git clone failed"
         }
     }
 
-    $docfxRestoreBinLogPath = Join-Path $buildInfo['BinLogsPath'] Ubiquity.NET.Llvm-docfx-Build.restore.binlog
-    $docfxBinLogPath = Join-Path $buildInfo['BinLogsPath'] Ubiquity.NET.Llvm-docfx-Build.binlog
+    # remove all contents from 'current' docs to ensure clean generated docs for this release
+    $currentVersionDocsPath = Join-Path $docsOutputPath 'current'
+    if(Test-Path -PathType Container $currentVersionDocsPath)
+    {
+        del -Path $currentVersionDocsPath -Recurse -Force
+    }
 
-    # DocFX.console build support is peculiar and a bit fragile, It requires a separate restore path or it won't do anything for the build target.
-    Write-Information "Restoring Docs Project"
-    Invoke-MSBuild -Targets 'Restore' -Project docfx\Ubiquity.NET.Llvm.DocFX.csproj -Properties $msBuildProperties -LoggerArgs ($buildInfo['MsBuildLoggerArgs'] + @("/bl:$docfxRestoreBinLogPath") )
+    $docfxRestoreBinLogPath = Join-Path $buildInfo['BinLogsPath'] Ubiquity.NET.Llvm-docfx-Restore.binlog
+    $docfxBuildBinLogPath = Join-Path $buildInfo['BinLogsPath'] Ubiquity.NET.Llvm-docfx-Build.binlog
 
-    Write-Information "Building Docs Project"
-    Invoke-MSBuild -Targets 'Build' -Project docfx\Ubiquity.NET.Llvm.DocFX.csproj -Properties $msBuildProperties -LoggerArgs ($buildInfo['MsBuildLoggerArgs'] + @("/bl:$docfxBinLogPath") )
+    Write-Information "Building Docs Solution"
+    Invoke-MSBuild -Targets 'Restore' -Project docfx\Ubiquity.NET.Llvm.DocFX.sln -Properties $msBuildProperties -LoggerArgs ($buildInfo['MsBuildLoggerArgs'] + @("/bl:$docfxRestoreBinLogPath") )
+    Invoke-MSBuild -Targets 'Build' -Project docfx\Ubiquity.NET.Llvm.DocFX.sln -Properties $msBuildProperties -LoggerArgs ($buildInfo['MsBuildLoggerArgs'] + @("/bl:$docfxBuildBinLogPath") )
 }
 catch
 {

BuildVersion.xml

@@ -3,4 +3,5 @@
     BuildMinor = "0"
     BuildPatch = "0"
     PreReleaseName = "alpha"
+    PreReleaseNumber ="1"
 />

OneFlow/Publish-Release.ps1

@@ -1,23 +1,6 @@
 . .\buildutils.ps1
 $buildInfo = Initialize-BuildEnvironment
 
-# determine release tag from the build version XML file in the branch
-[xml]$buildVersionXml = Get-Content .\BuildVersion.xml
-$buildVersionData = $buildVersionXml.BuildVersionData
-$preReleaseSuffix=""
-if($buildVersionData.PSObject.Properties['PreReleaseName'])
-{
-    $preReleaseSuffix = "-$($buildVersionData.PreReleaseName)"
-    if($buildVersionData.PSObject.Properties['PreReleaseNumber'])
-    {
-        $preReleaseSuffix += ".$($buildVersionData.PreReleaseNumber)"
-        if($buildVersionData.PSObject.Properties['PreReleaseFix'])
-        {
-            $preReleaseSuffix += ".$($buildVersionData.PreReleaseFix)"
-        }
-    }
-}
-
 # Release tags must only be pushed from a repository with the official GitHub repository as the origin remote.
 # This ensures that the links to source in the generated docs will have the correct URLs
 # (e.g. docs pushed to the official repository MUST not have links to source in some private fork)
@@ -31,7 +14,7 @@ if($remoteUrl -ine "https://github.com/UbiquityDotNET/Llvm.NET.git")
 }
 
 # pushing the tag to GitHub triggers the official build and release of the Nuget Packages
-$tagName = "v$($buildVersionData.BuildMajor).$($buildVersionData.BuildMinor).$($buildVersionData.BuildPatch)$preReleaseSuffix"
+$tagName = Get-BuildVersionTag
 $releaseBranch = "release/$tagName"
 $currentBranch = git rev-parse --abbrev-ref HEAD
 if( $releaseBranch -ne $currentBranch )

PsModules/CommonBuild/CommonBuild.psm1

@@ -37,6 +37,7 @@ function Get-DefaultBuildPaths([string]$repoRoot)
         NuGetRepositoryPath = Join-Path $buildOutputPath 'packages'
         NuGetOutputPath = Join-Path $buildOutputPath 'NuGet'
         SrcRootPath = Join-Path $repoRoot 'src'
+        DocsRepoPath = Join-Path $buildOutputPath 'docs'
         DocsOutputPath = Join-Path $buildOutputPath 'docs'
         BinLogsPath = Join-Path $buildOutputPath 'BinLogs'
         TestResultsPath = Join-Path $buildOutputPath 'Test-Results'
@@ -470,3 +471,33 @@ function Invoke-DotNetTest($buildInfo, $projectRelativePath)
     Write-Information $result
     return $LASTEXITCODE -ne 0
 }
+
+function Get-BuildVersionXML
+{
+    [OutputType([xml])]
+    param ()
+
+    # determine release tag from the build version XML file in the branch
+    [xml]$buildVersionXml = Get-Content .\BuildVersion.xml
+    return $buildVersionXml.BuildVersionData
+}
+
+function Get-BuildVersionTag
+{
+    Param([xml]$buildVersionData = (Get-BuildVersionXML))
+    $preReleaseSuffix=""
+    if($buildVersionData.PSObject.Properties['PreReleaseName'])
+    {
+        $preReleaseSuffix = "-$($buildVersionData.PreReleaseName)"
+        if($buildVersionData.PSObject.Properties['PreReleaseNumber'])
+        {
+            $preReleaseSuffix += ".$($buildVersionData.PreReleaseNumber)"
+            if($buildVersionData.PSObject.Properties['PreReleaseFix'])
+            {
+                $preReleaseSuffix += ".$($buildVersionData.PreReleaseFix)"
+            }
+        }
+    }
+
+    return "v$($buildVersionData.BuildMajor).$($buildVersionData.BuildMinor).$($buildVersionData.BuildPatch)$preReleaseSuffix"
+}

Push-Docs.ps1

@@ -63,7 +63,7 @@ try
     }
 
     cmd /c echo Committing changes to git
-    git commit -m "CI Docs Update"
+    git commit -m "CI Docs Update $(Get-BuildVersionTag)"
     if(!$?)
     {
         throw "git commit failed"

Samples/Kaleidoscope/Kaleidoscope.Parser/AST/Kaleidoscope-AST.md

@@ -6,31 +6,55 @@ uid: Kaleidoscope-AST
 As with many language parsing systems Kaleidoscope leverages an Abstract Syntax Tree (AST) to simplify
 generating code from the parsed language. Each type of node in the tree implements the IAstNode interface
 
-[!code-csharp[IAstNode](IAstNode.cs)]
-
 This interface provides the basic properties of any node in the tree for common uses. The Kaleidoscope
 language is a simple one and, therefore, has only a few kinds of nodes. The AST consist of the following
 basic categories of nodes:
- * Function Declarations
- * Function Definitions
- * Variable Declarations
-   * Local Variables
-   * Function Parameters
- * Expressions
-   * Variable Reference
-   * Unary Operators
-   * Binary Operators
-   * Function Call
-   * For-In Expression
-   * Assignment
-   * Var-In Expression
-
-## AST Nodes
+ * [AST Node](#ast-node)
+    * [Function Declaration](#function-declaration)
+    * [Function Definition](#function-definition)
+    * [Variable Declaration](#variable-declaration)
+      * [Local Variable](#local-variable)
+      * [Function Parameter](#function-parameter)
+    * [Expression](#expression)
+      * [Variable Reference](#variable-reference)
+      * [Unary Operator](#unary-operator)
+      * [Binary Operator](#binary-operator)
+         - [Assignment](#assignment)
+      * [Function Call](#function-call)
+      * [Conditional](#conditional)
+      * [For-In](#for-in)
+      * [Var-In](#var-in)
+
+## AST Node
 The IAstNode interface forms the common interface for all AST nodes, it provides the common properties
 for all nodes.
+
 [!code-csharp[IAstNode](IAstNode.cs)]
 
-## Expressions
+## Function Definition
+FunctionDefinition, as the name implies, contains the definition of a function. This includes the signature
+and the full body of the function.
+
+[!code-csharp[FunctionDefinition](FunctionDefinition.cs)]
+
+## Function Declaration
+[!code-csharp[Function Signatures (Prototype)](Prototype.cs)]
+
+## Variable Declaration
+IVariableDeclaration is implemented by local variable declarations and parameter declarations. The
+interface abstracts the differences between the two types of variable declarations for most common
+cases. Most code generation or AST consumers don't care about the differences (i.e. Parameters have
+an index but locals don't)
+
+[!code-csharp[IVariableDeclaration](IVariableDeclaration.cs)]
+
+### Local Variable
+[!code-csharp[Local Variable Declarations](LocalVariableDeclaration.cs)]
+
+### Function Parameter
+[!code-csharp[Parameter declarations](ParameterDeclaration.cs)]
+
+## Expression
 Kaleidoscope is a functional language, all expressions produce a value, even if it is always zero. There
 are no statements in the language. Expressions form the core of the language and the bulk of the AST.
 
@@ -43,12 +67,14 @@ for a binary operator so only nodes that implement the IExpression tag interface
 a common or generally recommended pattern for interfaces but makes sense here since some form of differentiation
 is needed.
 
-### Unary Operators
+### Unary Operator
 Unary operators are all user defined, so the AST simply represents them as a Function Definition. No
 additional node types are needed for unary operators in the AST.
 
-### Binary Operators
-BinaryOperatorExpression covers the built-in operators
+### Binary Operator
+BinaryOperatorExpression covers the built-in operators, any user defined binary operators are transformed
+to a function declaration/definition
+
 [!code-csharp[BinaryOperatorExpression](BinaryOperatorExpression.cs)]
 
 The properties are fairly self explanatory, including the kind of operator and the left and right sides of the
@@ -66,48 +92,32 @@ the left hand side is not an evaluated expression. Instead, it is the variable t
 there isn't anything to evaluate for the left hand side as it is always a Variable Reference for the variable to assign
 the value to.
 
-### Function Call Expression
+### Function Call
 Calls to functions (extern, user defined operators, or user defined functions) are represented in the AST as a
 FunctionCallExpression. The FunctionCallExpression contains the declaration of the function to call along with 
 expressions for all of the arguments to the function.
 
 [!code-csharp[FunctionCallExpression](FunctionCallExpression.cs)]
 
-### Variable Reference Expression
+### Variable Reference
 A variable reference is used to refer to a variable. In most cases this represents implicit "load" semantics for a
 variable. However, when used as the left hand side of an assignment operator, it has "store" semantics.
 
 [!code-csharp[VariableReferenceExpression](VariableReferenceExpression.cs)]
 
-### Conditional Expression
+### Conditional
 In Kaleidoscope conditional expressions follow the familiar if/then/else form, even though they are really more
 like the ternary operator expression `( x ? y : z )` in C and related languages.
 
 [!code-csharp[ConditionalExpression](ConditionalExpression.cs)]
 
-### For-In Expression
+### For-In
 The for in expression is used to implement loops in Kaleidoscope.
 
 [!code-csharp[ForInExpression](ForInExpression.cs)]
 
-### Var-In Expression
+### Var-In
 Var-In Expression is used to provide, potentially nested, local scopes for variables
 
 [!code-csharp[VarInExpression](VarInExpression.cs)]
 
-### Misc AST Interfaces
-IVariableDeclaration is implemented by local variable declarations and parameter declarations. The
-interface abstracts the differences between the two types of variable declarations. (Parameters have an index but locals don't)
-[!code-csharp[IVariableDeclaration](IVariableDeclaration.cs)]
-
-## Other AST Nodes
-### AST Declarations
-[!code-csharp[Function Signatures (Prototype)](Prototype.cs)]
-[!code-csharp[Local Variable Declarations](LocalVariableDeclaration.cs)]
-[!code-csharp[Parameter declarations](ParameterDeclaration.cs)]
-
-### AST FunctionDefinition
-FunctionDefinition, as the name implies, contains the definition of a function. This includes the signature
-and the full body of the function.
-
-[!code-csharp[FunctionDefinition](FunctionDefinition.cs)]

Samples/Kaleidoscope/Kaleidoscope.Parser/readme.md

@@ -1,9 +1,8 @@
 # Kaleidoscope Parser
 This library implements a Lexer/Parser for the Ubiquity.NET.Llvm Kaleidoscope tutorial.
 The language syntax follows that of the official LLVM C++ tutorial though, unlike
-the C++ version, all versions of the language (Chapters 2-7) use the same parser
-library. To accomplish this, the grammar takes advantage of the dynamic parsing
-support found in ANTLR4 so that various language features are enabled at runtime.
-This keeps the individual chapter samples a bit cleaner and focused on the use of
-Ubiquity.NET.Llvm instead of parsing. 
+the C++ version, all versions of the language use the same parser library. To accomplish
+this, the grammar takes advantage of the dynamic parsing support found in ANTLR4 so that
+various language features are enabled at runtime. This keeps the individual chapter samples
+a bit cleaner and focused on the use of Ubiquity.NET.Llvm instead of parsing. 
 

buildutils.ps1

@@ -1,4 +1,4 @@
-# Project specific common support
+# Project/Repo specific extensions to common support
 using module 'PSModules\CommonBuild\CommonBuild.psd1'
 
 Set-StrictMode -version 3.0

docfx/Ubiquity.NET.Llvm.Docfx.sln

@@ -3,7 +3,40 @@ Microsoft Visual Studio Solution File, Format Version 12.00
 # Visual Studio Version 16
 VisualStudioVersion = 16.0.29102.190
 MinimumVisualStudioVersion = 10.0.40219.1
-Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Ubiquity.NET.Llvm.Docfx", "Ubiquity.NET.Llvm.Docfx.csproj", "{E0C93719-295E-4A6B-B9FD-63A18FC4E447}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Ubiquity.NET.Llvm.Docfx.API", "current\Ubiquity.NET.Llvm.Docfx.API.csproj", "{E0C93719-295E-4A6B-B9FD-63A18FC4E447}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Ubiquity.NET.Llvm.Docfx.Index", "index\Ubiquity.NET.Llvm.Docfx.Index.csproj", "{D6505E72-CAEA-476B-B7E2-68DA1CDB9243}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "templates", "templates", "{F1EECBFA-02CE-4B14-A370-FFFA080250C6}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Ubiquity", "Ubiquity", "{9FAA1D8A-F467-472E-9AF2-6BDB22F5D475}"
+	ProjectSection(SolutionItems) = preProject
+		templates\Ubiquity\readme.md = templates\Ubiquity\readme.md
+	EndProjectSection
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "partials", "partials", "{353D26CA-B7C2-4037-9070-2CE87DEFD86F}"
+	ProjectSection(SolutionItems) = preProject
+		templates\Ubiquity\partials\affix.tmpl.partial = templates\Ubiquity\partials\affix.tmpl.partial
+		templates\Ubiquity\partials\class.header.tmpl.partial = templates\Ubiquity\partials\class.header.tmpl.partial
+		templates\Ubiquity\partials\class.tmpl.partial = templates\Ubiquity\partials\class.tmpl.partial
+		templates\Ubiquity\partials\collection.tmpl.partial = templates\Ubiquity\partials\collection.tmpl.partial
+		templates\Ubiquity\partials\enum.tmpl.partial = templates\Ubiquity\partials\enum.tmpl.partial
+		templates\Ubiquity\partials\footer.tmpl.partial = templates\Ubiquity\partials\footer.tmpl.partial
+		templates\Ubiquity\partials\namespace.tmpl.partial = templates\Ubiquity\partials\namespace.tmpl.partial
+	EndProjectSection
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "styles", "styles", "{D3F068B8-4A6C-46C4-8F1D-82AA544CB7E4}"
+	ProjectSection(SolutionItems) = preProject
+		templates\Ubiquity\styles\main.css = templates\Ubiquity\styles\main.css
+		templates\Ubiquity\styles\main.js = templates\Ubiquity\styles\main.js
+	EndProjectSection
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Resources", "Resources", "{80950FE7-B0E4-419E-87CC-1EE58C76421B}"
+	ProjectSection(SolutionItems) = preProject
+		DragonSharp.png = DragonSharp.png
+		DragonSharp48x48.png = DragonSharp48x48.png
+		favicon.ico = favicon.ico
+	EndProjectSection
 EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
@@ -15,10 +48,19 @@ Global
 		{E0C93719-295E-4A6B-B9FD-63A18FC4E447}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{E0C93719-295E-4A6B-B9FD-63A18FC4E447}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{E0C93719-295E-4A6B-B9FD-63A18FC4E447}.Release|Any CPU.Build.0 = Release|Any CPU
+		{D6505E72-CAEA-476B-B7E2-68DA1CDB9243}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{D6505E72-CAEA-476B-B7E2-68DA1CDB9243}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{D6505E72-CAEA-476B-B7E2-68DA1CDB9243}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{D6505E72-CAEA-476B-B7E2-68DA1CDB9243}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
 	EndGlobalSection
+	GlobalSection(NestedProjects) = preSolution
+		{9FAA1D8A-F467-472E-9AF2-6BDB22F5D475} = {F1EECBFA-02CE-4B14-A370-FFFA080250C6}
+		{353D26CA-B7C2-4037-9070-2CE87DEFD86F} = {9FAA1D8A-F467-472E-9AF2-6BDB22F5D475}
+		{D3F068B8-4A6C-46C4-8F1D-82AA544CB7E4} = {9FAA1D8A-F467-472E-9AF2-6BDB22F5D475}
+	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {4E9321AC-4ABF-4522-89CE-CD9A98005C92}
 	EndGlobalSection