Refactor the templating engine and the command tool cache et al. (#615)

* Use a more efficient implementation of the Common module functions.

Use an allocation-free implementation of the ParamKey type.
Fix formatting in BuildCommand.fs and syntax highlighting in _template.html.

* Rewrite the template engine to be more memory-efficient.

It uses spans. For the most of allocation savings, FSharp.Formatting.Common now targets .NET Standard 2.1 too but the package is not yet updated; only the command tool will take advantage of all improvements.

* Ignore files generated by the AssemblyInfo FAKE target.

Remove an unused source file.
And use LINQ-to-XML to generate version.props.

* Serialize the command tool cache with the data contract serializer.

The cache is both more secure and more compact (the cache's size for this project was reduced by a third, after using binary XML).
And use a more reliable way to install the command tools during documentation generation.

* Override ParamKey.ToString.

Author: teo-tsirpanis

.gitignore

@@ -38,4 +38,8 @@ _NCrunch_*
 .ionide/
 artifacts/
 tests/FSharp.ApiDocs.Tests/output/
-tmp
+tmp
+.idea/
+*.binlog
+version.props
+src/Common/AssemblyInfo.?s

Directory.Build.props

@@ -1,5 +1,5 @@
 <Project>
-  <Import Project="version.props" />
+  <Import Condition="Exists('version.props')" Project="version.props" />
   <PropertyGroup>
     <!-- Include PDBs in Nuget package. -->
     <AllowedOutputExtensionsInPackageBuildOutputFolder>.pdb; $(AllowedOutputExtensionsInPackageBuildOutputFolder)</AllowedOutputExtensionsInPackageBuildOutputFolder>

build.fsx

@@ -9,7 +9,7 @@
 #endif
 
 open System
-open System.IO
+open System.Xml.Linq
 open Fake.Core
 open Fake.Core.TargetOperators
 open Fake.IO.Globbing.Operators
@@ -52,15 +52,14 @@ Target.create "AssemblyInfo" (fun _ ->
 
     AssemblyInfoFile.createFSharp "src/Common/AssemblyInfo.fs" info
     AssemblyInfoFile.createCSharp "src/Common/AssemblyInfo.cs" info
-    let releaseNotes = String.toLines release.Notes |> System.Net.WebUtility.HtmlEncode
-    File.WriteAllText("version.props", sprintf """<Project>
-      <PropertyGroup>
-        <Version>%s</Version>
-        <PackageReleaseNotes>
-%s
-        </PackageReleaseNotes>
-      </PropertyGroup>
-    </Project>""" release.NugetVersion releaseNotes)
+    let versionProps =
+        XElement(XName.Get "Project",
+            XElement(XName.Get "PropertyGroup",
+                XElement(XName.Get "Version", release.NugetVersion),
+                XElement(XName.Get "PackageReleaseNotes", String.toLines release.Notes)
+            )
+        )
+    versionProps.Save("version.props")
 )
 
 // Clean build results
@@ -104,8 +103,8 @@ Target.create "Tests" (fun _ ->
 Target.create "NuGet" (fun _ ->
     DotNet.pack (fun pack ->
         { pack with
-            OutputPath = Some artifactsDir 
-            Configuration = configuration 
+            OutputPath = Some artifactsDir
+            Configuration = configuration
         }) solutionFile
 )
 
@@ -115,15 +114,15 @@ Target.create "NuGet" (fun _ ->
 Target.create "GenerateDocs" (fun _ ->
     Shell.cleanDir ".fsdocs"
     Shell.cleanDir ".packages"
-    DotNet.exec id "tool" "uninstall --local FSharp.Formatting.CommandTool" |> ignore
-    // Use a local package store to avoid reuse of previous builds of the package with the same version
-    try 
-      Environment.setEnvironVar "NUGET_PACKAGES" (__SOURCE_DIRECTORY__ + "/.packages")
-      DotNet.exec id "tool" ("install --local --no-cache --version " + release.NugetVersion + " --add-source " + artifactsDir + " FSharp.Formatting.CommandTool")  |> ignore
-    finally
-      Environment.setEnvironVar "NUGET_PACKAGES" ""
-    DotNet.exec id "fsdocs" "build --strict --clean --property Configuration=Release" |> ignore
-    DotNet.exec id "tool" "uninstall --local FSharp.Formatting.CommandTool" |> ignore
+    // Τhe tool has been uninstalled when the
+    // artifacts folder was removed in the Clean target.
+    DotNet.exec id "tool" ("install --no-cache --version " + release.NugetVersion + " --add-source " + artifactsDir + " --tool-path " + artifactsDir + " FSharp.Formatting.CommandTool")  |> ignore
+    CreateProcess.fromRawCommand (artifactsDir @@ "fsdocs") ["build"; "--strict"; "--clean"; "--property"; "Configuration=Release"]
+    |> CreateProcess.ensureExitCode
+    |> Proc.run
+    |> ignore
+    // DotNet.exec id "fsdocs" "build --strict --clean --property Configuration=Release" |> ignore
+    // DotNet.exec id "tool" "uninstall --local FSharp.Formatting.CommandTool" |> ignore
     Shell.cleanDir ".packages"
 )
 
@@ -146,7 +145,7 @@ Target.create "PublishNuget" (fun _ ->
     let apikey =  Environment.environVar "NUGET_KEY"
     for artifact in !! (artifactsDir + "/*nupkg") do
         let result = DotNet.exec id "nuget" (sprintf "push -s %s -k %s %s" source apikey artifact)
-        if not result.OK then failwith "failed to push packages"  
+        if not result.OK then failwith "failed to push packages"
 )
 
 Target.create "CreateTag" (fun _ ->

docs/_template.html

@@ -71,7 +71,7 @@ <h3 class="muted"><a href="{{fsdocs-collection-name-link}}">{{fsdocs-collection-
 
         <!-- BEGIN SEARCH BOX: this adds support for the search box -->
         <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/JavaScript-autoComplete/1.0.4/auto-complete.css" />
-        <script type="text/javascript">var fsdocs_search_baseurl = '{{root}}'</script>
+        <script type="text/javascript">var fsdocs_search_baseurl = '{{root}}';</script>
         <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/lunr.js/2.3.8/lunr.min.js"></script>
         <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/JavaScript-autoComplete/1.0.4/auto-complete.min.js"></script>
         <script type="text/javascript" src="{{root}}content/fsdocs-search.js"></script>

paket.dependencies

@@ -10,6 +10,7 @@ nuget Dotnet.ProjInfo
 nuget Dotnet.ProjInfo.Workspace
 nuget Newtonsoft.Json
 nuget Suave 2.1.1
+nuget System.Memory
 
 # Used to create notebook docs with mybinder links that work
 # See https://github.com/dotnet/interactive/blob/master/docs/CreateBinder.md