Ported PicklesHelper to FAKE 5

Fake.sln

@@ -114,6 +114,8 @@ Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "Fake.JavaScript.Yarn", "src
 EndProject
 Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "Fake.Sql.DacPac", "src/app/Fake.Sql.DacPac/Fake.Sql.DacPac.fsproj", "{3BC4A91C-3381-4BF9-BF11-8E06706CF878}"
 EndProject
+Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "Fake.Tools.Pickles", "src/app/Fake.Tools.Pickles/Fake.Tools.Pickles.fsproj", "{2EC1798B-3AD5-42FE-9406-F358B995ACC3}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -736,6 +738,18 @@ Global
 		{3BC4A91C-3381-4BF9-BF11-8E06706CF878}.Release|x64.Build.0 = Release|Any CPU
 		{3BC4A91C-3381-4BF9-BF11-8E06706CF878}.Release|x86.ActiveCfg = Release|Any CPU
 		{3BC4A91C-3381-4BF9-BF11-8E06706CF878}.Release|x86.Build.0 = Release|Any CPU
+		{2EC1798B-3AD5-42FE-9406-F358B995ACC3}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{2EC1798B-3AD5-42FE-9406-F358B995ACC3}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{2EC1798B-3AD5-42FE-9406-F358B995ACC3}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{2EC1798B-3AD5-42FE-9406-F358B995ACC3}.Debug|x64.Build.0 = Debug|Any CPU
+		{2EC1798B-3AD5-42FE-9406-F358B995ACC3}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{2EC1798B-3AD5-42FE-9406-F358B995ACC3}.Debug|x86.Build.0 = Debug|Any CPU
+		{2EC1798B-3AD5-42FE-9406-F358B995ACC3}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{2EC1798B-3AD5-42FE-9406-F358B995ACC3}.Release|Any CPU.Build.0 = Release|Any CPU
+		{2EC1798B-3AD5-42FE-9406-F358B995ACC3}.Release|x64.ActiveCfg = Release|Any CPU
+		{2EC1798B-3AD5-42FE-9406-F358B995ACC3}.Release|x64.Build.0 = Release|Any CPU
+		{2EC1798B-3AD5-42FE-9406-F358B995ACC3}.Release|x86.ActiveCfg = Release|Any CPU
+		{2EC1798B-3AD5-42FE-9406-F358B995ACC3}.Release|x86.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -794,6 +808,7 @@ Global
 		{B636A082-4DB4-439D-8A37-E5214BDC00A3} = {901F162F-8925-4390-89C5-9EE2C343F744}
 		{DE7579F2-C20F-4C35-BC04-C10362912243} = {901F162F-8925-4390-89C5-9EE2C343F744}
 		{3BC4A91C-3381-4BF9-BF11-8E06706CF878} = {7BFFAE76-DEE9-417A-A79B-6A6644C4553A}
+		{2EC1798B-3AD5-42FE-9406-F358B995ACC3} = {7BFFAE76-DEE9-417A-A79B-6A6644C4553A}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {058A0C5E-2216-4306-8AFB-0AE28320C26A}

build.fsx

@@ -292,6 +292,7 @@ let dotnetAssemblyInfos =
       "Fake.netcore", "Command line tool"
       "Fake.Runtime", "Core runtime features"
       "Fake.Tools.Git", "Running git commands"
+      "Fake.Tools.Pickles", "Convert Gherkin to HTML"
       "Fake.Testing.Common", "Common testing data types"
       "Fake.Tracing.NAntXml", "NAntXml"
       "Fake.Windows.Chocolatey", "Running and packaging with Chocolatey"

help/markdown/fake-tools-pickles.md

@@ -0,0 +1,31 @@
+# Convert Gherkin to HTML with Pickles
+
+[Pickles] is a Living Documentation generator: it takes your Specification (written in Gherkin, with Markdown descriptions) and turns them into an always up-to-date documentation of the current state of your software - in a variety of formats.
+
+## Minimal working example
+
+```fsharp
+#r "paket:
+nuget Fake.Core.Target
+nuget Fake.IO.FileSystem
+nuget Fake.Tools.Pickles //"
+
+open Fake.Core
+open Fake.Core.TargetOperators
+open Fake.IO.FileSystemOperators
+open Fake.Tools
+open System.IO
+
+let currentDirectory = Directory.GetCurrentDirectory()
+
+Target.create "BuildDoc" (fun _ ->
+    Pickles.convert (fun p ->
+        { p with FeatureDirectory = currentDirectory </> "Specs"
+                 OutputDirectory = currentDirectory </> "SpecDocs"
+                 OutputFileFormat = Pickles.DocumentationFormat.DHTML })
+)
+
+Target.runOrDefault "BuildDoc"
+```
+
+[Pickles]: http://www.picklesdoc.com/

help/templates/template.cshtml

@@ -128,6 +128,7 @@
 															<a href="@(prefix)apidocs/index.html#Fake.Tools.Git">Tools</a>
 															<ul>
 																<li><a href="@(prefix)apidocs/index.html#Fake.Tools.Git">Git</a></li>
+																<li><a href="@(prefix)fake-tools-pickles.html">Pickles</a></li>
 															</ul>
 														</li>
 														<li>

src/app/Fake.Tools.Pickles/AssemblyInfo.fs

@@ -0,0 +1,17 @@
+// Auto-Generated by FAKE; do not edit
+namespace System
+open System.Reflection
+
+[<assembly: AssemblyTitleAttribute("FAKE - F# Make Convert Gherkin to HTML")>]
+[<assembly: AssemblyProductAttribute("FAKE - F# Make")>]
+[<assembly: AssemblyVersionAttribute("5.0.0")>]
+[<assembly: AssemblyInformationalVersionAttribute("5.0.0-rc005")>]
+[<assembly: AssemblyFileVersionAttribute("5.0.0")>]
+do ()
+
+module internal AssemblyVersionInformation =
+    let [<Literal>] AssemblyTitle = "FAKE - F# Make Convert Gherkin to HTML"
+    let [<Literal>] AssemblyProduct = "FAKE - F# Make"
+    let [<Literal>] AssemblyVersion = "5.0.0"
+    let [<Literal>] AssemblyInformationalVersion = "5.0.0-rc005"
+    let [<Literal>] AssemblyFileVersion = "5.0.0"

src/app/Fake.Tools.Pickles/Fake.Tools.Pickles.fsproj

@@ -0,0 +1,25 @@
+<Project Sdk="Microsoft.NET.Sdk" ToolsVersion="15.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+  <PropertyGroup>
+    <TargetFrameworks>net46;netstandard1.6;netstandard2.0</TargetFrameworks>
+    <DefineConstants>$(DefineConstants);NO_DOTNETCORE_BOOTSTRAP</DefineConstants>
+    <AssemblyName>Fake.Tools.Pickles</AssemblyName>
+    <OutputType>Library</OutputType>
+  </PropertyGroup>
+  <PropertyGroup>
+    <DefineConstants>$(DefineConstants);NETSTANDARD;USE_HTTPCLIENT</DefineConstants>
+  </PropertyGroup>
+  <PropertyGroup Condition=" '$(Configuration)' == 'Release' ">
+    <DefineConstants>$(DefineConstants);RELEASE</DefineConstants>
+  </PropertyGroup>
+  <ItemGroup>
+    <Compile Include="AssemblyInfo.fs" />
+    <Compile Include="Pickles.fs" />
+  </ItemGroup>
+  <ItemGroup>
+    <ProjectReference Include="..\Fake.Core.Process\Fake.Core.Process.fsproj" />
+    <ProjectReference Include="..\Fake.Core.String\Fake.Core.String.fsproj" />
+    <ProjectReference Include="..\Fake.Core.Trace\Fake.Core.Trace.fsproj" />
+    <ProjectReference Include="..\Fake.IO.FileSystem\Fake.IO.FileSystem.fsproj" />
+  </ItemGroup>
+  <Import Project="..\..\..\.paket\Paket.Restore.targets" />
+</Project>

src/app/Fake.Tools.Pickles/Pickles.fs

@@ -0,0 +1,224 @@
+/// Contains tasks to run the [Pickles](http://www.picklesdoc.com/) living documentation generator
+///
+/// ## Sample usage
+/// 
+/// ```
+/// open Fake.Tools
+/// 
+/// Target "BuildDoc" (fun _ ->
+///     Pickles.convert (fun p -> { p with
+///                                 FeatureDirectory = currentDirectory @@ "Specs"
+///                                 OutputDirectory = currentDirectory @@ "SpecDocs" })
+/// )
+/// ```
+///
+
+[<RequireQualifiedAccess>]
+module Fake.Tools.Pickles
+
+open System
+open System.Text
+open Fake.Core
+open Fake.IO
+open Fake.IO.Globbing
+open Fake.IO.FileSystemOperators
+open System.IO
+
+(*
+.\packages\Pickles.CommandLine\tools\pickles.exe  --help                                                 
+Pickles version 2.18.1.0
+  -f, --feature-directory=VALUE
+                             directory to start scanning recursively for
+                               features
+  -o, --output-directory=VALUE
+                             directory where output files will be placed
+      --trfmt, --test-results-format=VALUE
+                             the format of the linked test results
+                               (nunit|nunit3|xunit|xunit2|mstest
+                               |cucumberjson|specrun|vstest)
+      --lr, --link-results-file=VALUE
+                             the path to the linked test results file (can be
+                               a semicolon-separated list of files)
+      --sn, --system-under-test-name=VALUE
+                             the name of the system under test
+      --sv, --system-under-test-version=VALUE
+                             the version of the system under test
+  -l, --language=VALUE       the language of the feature files
+      --df, --documentation-format=VALUE
+                             the format of the output documentation
+  -v, --version
+  -h, -?, --help
+      --exp, --include-experimental-features
+                             whether to include experimental features
+      --cmt, --enableComments=VALUE
+                             whether to enable comments in the output
+      --et, --excludeTags=VALUE
+                             exclude scenarios that match this tag
+*)
+
+/// Option which allows to specify if failure of pickles should break the build.
+type ErrorLevel = 
+    /// This option instructs FAKE to break the build if pickles fails to execute
+    | Error
+    /// With this option set, no exception is thrown if pickles fails to execute
+    | DontFailBuild
+
+/// The format of the test results
+type TestResultsFormat =
+    | NUnit
+    | NUnit3
+    | XUnit
+    | XUnit2
+    | MSTest
+    | CucumberJSON
+    | SpecRun
+    | VSTest
+
+ type DocumentationFormat =
+    | DHTML
+    | HTML
+    | Word
+    | JSON
+    | Excel
+
+/// The Pickles parameter type
+type PicklesParams =
+    { /// The path to the Pickles console tool: 'pickles.exe'      
+      ToolPath : string
+      /// The directory to start scanning recursively for features
+      FeatureDirectory: string
+      /// The language of the feature files
+      FeatureFileLanguage: string option
+      /// The directory where output files will be placed
+      OutputDirectory: string
+      /// The format of the output documentation 
+      OutputFileFormat: DocumentationFormat
+      /// the format of the linked test results
+      TestResultsFormat: TestResultsFormat
+      /// the paths to the linked test results files
+      LinkedTestResultFiles: string list
+      /// The name of the system under test
+      SystemUnderTestName: string option
+      /// The version of the system under test
+      SystemUnderTestVersion: string option
+      /// Maximum time to allow xUnit to run before being killed.
+      TimeOut : TimeSpan
+      /// Option which allows to specify if failure of pickles should break the build.
+      ErrorLevel : ErrorLevel
+      /// Option which allows to enable some experimental features
+      IncludeExperimentalFeatures : bool option
+    }
+
+let private currentDirectory = Directory.GetCurrentDirectory()
+
+/// The Pickles default parameters
+///
+/// ## Defaults 
+///
+/// - `ToolPath` - The `pickles.exe` if it exists in a subdirectory of the current directory
+/// - `FeatureDirectory` - 'currentDirectory'
+/// - `FeatureFileLanguage` - 'None' (defaults to `en`)
+/// - `OutputDirectory` - `currentDirectory @@ "Documentation"`
+/// - `OutputFileFormat` - `DHTML`
+/// - `TestResultsFormat` - `Nunit`
+/// - `LinkedTestResultFiles` - []
+/// - `SystemUnderTestName` - `None`
+/// - `SystemUnderTestVersion` - `None`
+/// - `TimeOut` - 5 minutes
+/// - `ErrorLevel` - `Error`
+/// - `IncludeExperimentalFeatures` - `None` 
+let private PicklesDefaults =
+    {
+      ToolPath = Tools.findToolInSubPath "pickles.exe" currentDirectory
+      FeatureDirectory = currentDirectory
+      FeatureFileLanguage = None
+      OutputDirectory = currentDirectory </> "Documentation"
+      OutputFileFormat = DHTML
+      TestResultsFormat = NUnit
+      LinkedTestResultFiles = []
+      SystemUnderTestName = None
+      SystemUnderTestVersion = None
+      TimeOut = TimeSpan.FromMinutes 5.
+      ErrorLevel = Error
+      IncludeExperimentalFeatures = None
+    }
+
+let private buildPicklesArgs parameters =
+    let outputFormat = match parameters.OutputFileFormat with
+                       | DHTML -> "dhtml"
+                       | HTML -> "html"
+                       | Word -> "word"
+                       | JSON -> "json"
+                       | Excel -> "excel"
+
+    let testResultFormat = match parameters.LinkedTestResultFiles with
+                           | [] -> None
+                           | _  -> match parameters.TestResultsFormat with
+                                   | NUnit -> Some "nunit"
+                                   | NUnit3 -> Some "nunit3"
+                                   | XUnit -> Some "xunit"
+                                   | XUnit2 -> Some "xunit2"
+                                   | MSTest -> Some "mstest"
+                                   | CucumberJSON -> Some "cucumberjson"
+                                   | SpecRun -> Some "specrun"
+                                   | VSTest -> Some "vstest"
+
+    let linkedResultFiles = match parameters.LinkedTestResultFiles with
+                            | [] -> None
+                            | _ -> parameters.LinkedTestResultFiles
+                                   |> Seq.map (fun f -> sprintf "\"%s\"" f) 
+                                   |> String.concat ";"
+                                   |> Some
+    let experimentalFeatures = match parameters.IncludeExperimentalFeatures with
+                               | Some true -> Some "--exp"
+                               | _ -> None
+
+    new StringBuilder()
+    |> StringBuilder.appendWithoutQuotes (sprintf " -f \"%s\"" parameters.FeatureDirectory)
+    |> StringBuilder.appendWithoutQuotes (sprintf " -o \"%s\"" parameters.OutputDirectory)
+    |> StringBuilder.appendIfSome parameters.SystemUnderTestName (sprintf " --sn %s")
+    |> StringBuilder.appendIfSome parameters.SystemUnderTestVersion (sprintf " --sv %s")
+    |> StringBuilder.appendIfSome parameters.FeatureFileLanguage (sprintf " -l %s")
+    |> StringBuilder.appendWithoutQuotes (sprintf " --df %s" outputFormat)
+    |> StringBuilder.appendIfSome testResultFormat (sprintf " --trfmt %s")
+    |> StringBuilder.appendIfSome linkedResultFiles (sprintf " --lr %s")
+    |> StringBuilder.appendIfSome experimentalFeatures (sprintf "%s")
+    |> StringBuilder.toText
+
+module internal ResultHandling = 
+    let (|OK|Failure|) = function
+        | 0 -> OK
+        | x -> Failure x
+
+    let buildErrorMessage = function
+        | OK -> None
+        | Failure errorCode ->
+            Some (sprintf "Pickles reported an error (Error code %d)" errorCode)
+
+    let failBuildWithMessage = function
+        | DontFailBuild -> Trace.traceImportant
+        | _ -> failwith
+
+    let failBuildIfPicklesReportedError errorLevel =
+        buildErrorMessage
+        >> Option.iter (failBuildWithMessage errorLevel)
+
+/// Runs pickles living documentation generator via the given tool
+/// Will fail if the pickles command line tool terminates with a non zero exit code.
+///
+/// The pickles command line tool terminates with a non-zero exit code if there
+/// is any error.
+///
+/// ## Parameters
+///  - `setParams` - Function used to manipulate the default `PicklesParams` value
+let convert setParams =
+    use __ = Trace.traceTask "Pickles" ""
+    let parameters = setParams PicklesDefaults
+    let makeProcessStartInfo info =
+        { info with FileName = parameters.ToolPath
+                    WorkingDirectory = "."
+                    Arguments = parameters |> buildPicklesArgs } 
+
+    let result = Process.execSimple makeProcessStartInfo  parameters.TimeOut
+
+    ResultHandling.failBuildIfPicklesReportedError parameters.ErrorLevel result

src/app/Fake.Tools.Pickles/paket.references

@@ -0,0 +1,4 @@
+group netcore
+
+FSharp.Core
+NETStandard.Library