Docs update (#48)

* Docs update
* Complete refactoring of docs build. The docs are now built as a distinct project and included in the Llvm.NET.sln
* removed Build-docs.ps1 and updated Appveyor build support for the docs
* Buildall.ps1 now really does build all.
* Customized docs template/theme to use a dark theme that more closely resembles the dark theme of the .NET APIs
* added syntax highlighting for llvm-IR and rudimentary ANTLR grammar support for docs.

* Fixed buildall.ps1 for appveyor builds so the BuildOutput folder exists to clone the docs repo into

Author: smaillet

BuildAll.ps1

@@ -45,6 +45,20 @@ try
 
     md BuildOutput\NuGet\ | Out-Null
 
+    if( $env:CI -and !(Test-Path ".\BuildOutput\docs\.git" -PathType Container))
+    {
+        Write-Information "Cloning Docs repo"
+        pushd BuildOutput -ErrorAction Stop
+        try
+        {
+            git clone https://github.com/UbiquityDotNET/Llvm.NET.git -b gh-pages docs -q
+        }
+        finally
+        {
+            popd
+        }
+    }
+
     $BuildInfo = Get-BuildInformation $buildPaths
     if($env:APPVEYOR)
     {

Directory.Build.props

@@ -61,7 +61,7 @@
                 <IsTestProject>$(MSBuildProjectName.Contains('Test'))</IsTestProject>
             </PropertyGroup>
             <ItemGroup Condition="'$(NoCommonAnalyzers)'!='true' and '$(IsTestProject)' != 'true' and '$(SourceLinkEnabled)' != 'false'">
-                 <PackageReference Include="SourceLink.Create.CommandLine" Version="2.6.1" PrivateAssets="All" />
+                 <PackageReference Include="SourceLink.Create.CommandLine" Version="2.7.4" PrivateAssets="All" />
             </ItemGroup>
             <ItemGroup Condition="'$(NoCommonAnalyzers)'!='true'">
                 <PackageReference Include="Microsoft.AnalyzerPowerPack" Version="1.1.0" PrivateAssets="All" />

GOVERNANCE.md

@@ -79,7 +79,7 @@ Users should be encouraged to participate in the life of the project and the com
 contributions enable the project team to ensure that they are satisfying the needs of those users. Common user
 activities include (but are not limited to):
 
-* Evangelising about the project
+* Evangelizing about the project
 * Informing developers of project strengths and weaknesses from a new user’s perspective
 * Providing moral support (a ‘thank you’ goes a long way)
 * Providing financial support
@@ -90,7 +90,7 @@ involved. Such users may then go on to become contributors, as described above.
 ### Support
 
 All participants in the community are encouraged to provide support for new users within the project management
-infrastructure. This support is provided as a way of growing the community. Those seeking support should recognise that
+infrastructure. This support is provided as a way of growing the community. Those seeking support should recognize that
 all support activity within the project is voluntary and is therefore provided as and when time allows. A user requiring
 guaranteed response times or results should therefore seek to purchase a support contract from a vendor. (Of course,
 that vendor should be an active member of the community.) However, for those willing to engage with the project on its

README.md

@@ -36,34 +36,42 @@ C API with a C# adapter layer to provide the full experience .NET developers exp
 tedious one very little application code required changes.
 
 ### Platform Support
-Currently LLVM.NET supports Win32 and x64 buids targeting the full desktop framework v4.7 and .NET standard 2.0. Idealy other platforms are possible in the future. To keep life simpler the Llvm.NET nuget package is built for the "AnyCPU" platform and references the LibLLVM.NET package to bring in the native binary support. Llvm.NET contains code to dynamically detect the platform it is running on and load the appropriate DLL. This allows applications to build for AnyCPU without creating multiple build configurations and release vehicles for applications. (Any new platforms would need to update the dynamic loading support and include the appropriate P/Invokable binaries)
+Currently LLVM.NET supports Win32 and x64 builds targeting the full desktop framework v4.7 and .NET standard 2.0. Ideally
+other platforms are possible in the future. To keep life simpler the Llvm.NET NuGet package is built for the "AnyCPU"
+platform and references the LibLLVM.NET package to bring in the native binary support. Llvm.NET contains code to dynamically
+detect the platform it is running on and load the appropriate DLL. This allows applications to build for AnyCPU without
+creating multiple build configurations and release vehicles for applications. (Any new platforms would need to update the
+dynamic loading support and include the appropriate P/Invokable binaries)
 
-### CI Build Nuget Packages
-The CI Builds on AppVeyor provide a [Nuget Feed](https://ci.appveyor.com/nuget/Ubiquity.Llvm.NET
-) of the NuGet package built from the lates source in the master branch. 
+### CI Build NuGet Packages
+The CI Builds on AppVeyor provide a [NuGet Feed](https://ci.appveyor.com/NuGet/Ubiquity.Llvm.NET
+) of the NuGet package built from the latest source in the master branch. 
 
-### Building Llvm.NET
-#### Pre-requsites
+### API Documentation
+The full API documentation on using Llvm.NET is available on the [Llvm.NET documentation site](https://ubiquitydotnet.github.io/Llvm.NET/).
+
+## Building Llvm.NET
+### Pre-requsites
 * Visual Studio 2017 (15.4+)
-* Llvm.Libs Nuget Package
-  - To build the Llvm.Libs nuget package locally you can use the build support from the [Llvm.Libs ](https://github.com/UbiquityDotNET/Llvm.Libs) repository
+* Llvm.Libs NuGet Package
+  - To build the Llvm.Libs NuGet package locally you can use the build support from the [Llvm.Libs ](https://github.com/UbiquityDotNET/Llvm.Libs) repository
 
 #### Using Visual Studio
 The repository contains a Visual Studio solution files that allow building the components individually for modifying
 Llvm.NET and LibLLVM, as well as running the available unit tests. This is the primary mode of working with the
-Llvm.NET source code duing development.
+Llvm.NET source code during development.
 
-#### Replicating the automated build
-The Automated build support for Llvm.NET uses BuildAll.ps1 powershell script to build all the binaries, sign them
-[SHA256 hash only at present], and generate a nuget package. To build the full package simply run `BuildAll.ps1`
-from a powershell command prompt with msbuild tools on the system search path.
+### Replicating the automated build
+The Automated build support for Llvm.NET uses BuildAll.ps1 PowerShell script to build all the binaries, sign them
+[SHA256 hash only at present], and generate a NuGet package. To build the full package simply run `BuildAll.ps1`
+from a PowerShell command prompt with MSBuild tools on the system search path.
 
-#### Sample Application
+### Sample Application
 The [CodeGenWithDebugInfo](https://github.com/UbiquityDotNET/Llvm.Net/tree/master/Samples/CodeGenWithDebugInfo) sample application provides an example of using Llvm.NET to generate
 LLVM Bit code equivalent to what the Clang compiler generates for a [simple C language file](https://github.com/UbiquityDotNET/Llvm.Net/blob/master/Samples/CodeGenWithDebugInfo/Support%20Files/test.c).
-The sample applictation doesn't actually parse the source, instead it is a manually constructed and documented example of how to use Llvm.NET to accomplish the bit-code generation. 
+The sample application doesn't actually parse the source, instead it is a manually constructed and documented example of how to use Llvm.NET to accomplish the bit-code generation. 
 
-#### Code of Conduct
+### Code of Conduct
 This project has adopted the code of conduct defined by the [Contributor Covenant](http://contributor-covenant.org/)
 to clarify expected behavior in our community. For more information, see the
 [.NET Foundation Code of Conduct.](http://www.dotnetfoundation.org/code-of-conduct)

Samples/Kaleidoscope/Kaleidoscope.Parser/Kaleidoscope.g4

@@ -1,6 +1,6 @@
 // ANTLR4 Grammar for the LLVM Tutorial Sample Kaleidoscope language
 // To support a progression through the chapters the language features are
-// selectable and dynamicly adjust the parsing accordingly. This allows a
+// selectable and dynamically adjust the parsing accordingly. This allows a
 // single parser implementation for all chapters, which allows the tutorial
 // to focus on the actual use of Llvm.NET itself rather than on parsing.
 //

appveyor.yml

@@ -25,6 +25,9 @@ nuget:
 build_script:
   - ps: .\BuildAll.ps1
 
+deploy_script:
+  - ps: .\Push-Docs.ps1
+
 test_script:
   - ps: .\Invoke-UnitTests.ps1
   - ps: Set-Culture fr-FR; .\Invoke-UnitTests.ps1

docfx/Llvm.Net.Docfx.csproj

@@ -0,0 +1,59 @@
+<Project>
+    <Import Project="Sdk.props" Sdk="Microsoft.NET.Sdk" />
+    <PropertyGroup>
+        <TargetFramework>net47</TargetFramework>
+    </PropertyGroup>
+
+    <PropertyGroup>
+        <CompileDependsOn>ResolveReferences;BeforeCompile</CompileDependsOn>
+    </PropertyGroup>
+    
+    <ItemGroup>
+        <ProjectReference Include="..\src\Llvm.NET\Llvm.NET.csproj">
+            <PrivateAssets>All</PrivateAssets>
+            <Private>false</Private>
+        </ProjectReference>
+    </ItemGroup>
+
+    <ItemGroup>
+        <None Remove="Docfx-*.log" />
+    </ItemGroup>
+
+    <ItemGroup>
+        <PackageReference Include="docfx.console" Version="2.29.1" Condition="'$(TargetFramework)'=='net47'" PrivateAssets="All" />
+        <PackageReference Include="memberpage" Version="2.29.1" Condition="'$(TargetFramework)'=='net47'" PrivateAssets="All" />
+        <PackageReference Include="msdn.4.5.2" Version="0.1.0-alpha-1611021200" Condition="'$(TargetFramework)'=='net47'" PrivateAssets="All" />
+    </ItemGroup>
+
+    <Import Project="Sdk.targets" Sdk="Microsoft.NET.Sdk" />
+
+    <Target Name="GetDocfxPackagePaths" BeforeTargets="DocBuild">
+        <ItemGroup>
+            <docfxpkg Include="@(PackageDefinitions)" Condition="'%(PackageDefinitions.Name)'=='docfx.console'" />
+            <memberpage Include="@(PackageDefinitions)" Condition="'%(PackageDefinitions.Name)'=='memberpage'" />
+            <Msdn4_5_2 Include="@(PackageDefinitions)" Condition="'%(PackageDefinitions.Name)'=='msdn.4.5.2'" />
+            <DocFxInputAssembly Include="@(ReferencePath)" Condition="'%(ReferencePath.ReferenceSourceTarget)'=='ProjectReference'" />
+        </ItemGroup>
+        <PropertyGroup>
+            <DocfxConsolePath>%(docfxpkg.ResolvedPath)</DocfxConsolePath>
+            <MemberPagePath>%(memberpage.ResolvedPath)</MemberPagePath>
+            <MsdnXRefPath>%(msdn4_5_2.ResolvedPath)</MsdnXRefPath>
+            <LogLevel>Warning</LogLevel>
+            <LogFile>Docfx-$(TargetFramework).log</LogFile>
+            <DocParameters>$(DocParameters) --disableGitFeatures</DocParameters>
+            <DocParameters>$(DocParameters) --cleanupCacheHistory</DocParameters>
+            <DocParameters>$(DocParameters) --lruSize=0</DocParameters>
+            <DocParameters>$(DocParameters) --intermediateFolder=$(IntermediateOutputPath)</DocParameters>
+            <DocParameters>$(DocParameters) --xref=llvm-xref.yml,$(MsdnXrefPath)\content\msdn.4.5.2.zip,$(MsdnXrefPath)\content\namespaces.4.5.2.zip</DocParameters>
+            <DocTemplate>statictoc,$(MemberPagePath)\content,templates\Ubiquity</DocTemplate>
+        </PropertyGroup>
+        <Message Importance="high" Text="DocFxInputAssembly: %(DocFxInputAssembly.ReferenceAssembly)" />
+    </Target>
+
+    <!-- Stub the build target as this project only builds the documentation -->
+    <Target Name="CoreCompile" DependsOnTargets="$(CoreCompileDependsOn)">
+    </Target>
+
+    <Target Name="CopyFilesToOutputDirectory">
+    </Target>
+</Project>

docfx/articles/Samples/Kaleidoscope.md

@@ -110,7 +110,7 @@ When entered ( or copy/pasted) to the command line Kaleidoscope will print out t
 >This example uses features of the language only enabled/discussed in Chapter 6 of the tutorial.
 >The runtime from earlier chapters will generate errors trying to parse this code.
 
-```
+```shell
 Ready>mandel(-2.3, -1.3, 0.05, 0.07);
 *******************************************************************************
 *******************************************************************************

docfx/docfx.json

@@ -5,7 +5,7 @@
       "src":
       [
         {
-          "files": [ "src/Llvm.Net/**.cs"  ],
+          "files": [ "src/Llvm.Net/**.cs" ],
           "src":".."
         }
       ],
@@ -18,7 +18,6 @@
   ],
   "build":
   {
-    "xref": [ "llvm-xref.yml", "../tools/msdn.4.5.2/content/msdn.4.5.2.zip", "../tools/msdn.4.5.2/content/namespaces.4.5.2.zip"],
     "content":
     [
       {
@@ -60,8 +59,8 @@
       "_appFooter" : "Copyright (C) 2017, Dot NET Foundation",
       "_appLogoPath": "DragonSharp48x48.png",
       "_disableBreadcrumb" : true,
-      "llvmVersion": "5.0.0"
+      "llvmVersion": "5.0.0",
+      "assemblies": ["Llvm.NET"],
     },
-    "template": ["statictoc","../tools/memberpage/content","templates/Ubiquity"]
   }
 }

docfx/llvm-xref.yml

@@ -1,22 +1,22 @@
 references:
   - uid: llvm_langref
     name: LLVM Language reference
-    href: http://releases.llvm.org/5.0.0/docs/LangRef.html
+    href: http://releases.llvm.org/5.0.1/docs/LangRef.html
   - uid: llvm_sourceleveldebugging
     name: LLVM Source Level Debugging
-    href: http://releases.llvm.org/5.0.0/docs/SourceLevelDebugging.html
+    href: http://releases.llvm.org/5.0.1/docs/SourceLevelDebugging.html
   - uid: llvm_docs_garbagecollection
     name: LLVM Garbage Collection
-    href: http://releases.llvm.org/5.0.0/docs/GarbageCollection.html
+    href: http://releases.llvm.org/5.0.1/docs/GarbageCollection.html
   - uid: llvm_docs_passes
     name: LLVM Analysis and Transform Passes
-    href: http://releases.llvm.org/5.0.0/docs/Passes.html
+    href: http://releases.llvm.org/5.0.1/docs/Passes.html
   - uid: llvm_exception_handling
     name: LLVM Exception Handling
-    href: http://releases.llvm.org/5.0.0/docs/ExceptionHandling.html
+    href: http://releases.llvm.org/5.0.1/docs/ExceptionHandling.html
   - uid: llvm_misunderstood_gep
     name: LLVM The Misunderstood GEP Instruction
-    href: http://releases.llvm.org/5.0.0/docs/GetElementPtr.html
+    href: http://releases.llvm.org/5.0.1/docs/GetElementPtr.html
   - uid: llvm_sourcelevel_debugging
     name: LLVM Source Level Debugging
-    href: http://releases.llvm.org/5.0.0/docs/SourceLevelDebugging.html
+    href: http://releases.llvm.org/5.0.1/docs/SourceLevelDebugging.html