From 085342851f768f91b2214c3762697dba779dd97e Mon Sep 17 00:00:00 2001 From: unknown Date: Thu, 4 Feb 2016 11:01:41 +0100 Subject: [PATCH] Add PicklesHelper for generating living documentation with Pickles * see http://www.picklesdoc.com --- src/app/FakeLib/FakeLib.fsproj | 1 + src/app/FakeLib/PicklesHelper.fs | 188 +++++++++++++++++++++++++++++++ 2 files changed, 189 insertions(+) create mode 100644 src/app/FakeLib/PicklesHelper.fs diff --git a/src/app/FakeLib/FakeLib.fsproj b/src/app/FakeLib/FakeLib.fsproj index 308ddfcc4b7..cf643712a3f 100644 --- a/src/app/FakeLib/FakeLib.fsproj +++ b/src/app/FakeLib/FakeLib.fsproj @@ -173,6 +173,7 @@ + diff --git a/src/app/FakeLib/PicklesHelper.fs b/src/app/FakeLib/PicklesHelper.fs new file mode 100644 index 00000000000..8c107599b92 --- /dev/null +++ b/src/app/FakeLib/PicklesHelper.fs @@ -0,0 +1,188 @@ +[] +/// Contains tasks to run the [Pickles](http://http://www.picklesdoc.com/) living documentation generator +module Fake.PicklesHelper + +open System +open System.IO +open System.Text +open Fake + +(* +.\packages\Pickles.CommandLine\tools\pickles.exe --help +Pickles version 2.3.0.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|xunit) + --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 +*) + +/// Option which allows to specify if failure of pickles should break the build. +type PicklesErrorLevel = + /// 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 + | XUnit + + 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 : PicklesErrorLevel + } + +/// 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` +let PicklesDefaults = + { + ToolPath = 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 + } + +let 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" + | XUnit -> Some "xunit" + + let linkedResultFiles = match parameters.LinkedTestResultFiles with + | [] -> None + | _ -> parameters.LinkedTestResultFiles + |> Seq.map (fun f -> sprintf "\"%s\"" f) + |> String.concat ";" + |> Some + + new StringBuilder() + |> appendWithoutQuotes (sprintf " -f \"%s\"" parameters.FeatureDirectory) + |> appendWithoutQuotes (sprintf " -o \"%s\"" parameters.OutputDirectory) + |> appendIfSome parameters.SystemUnderTestName (sprintf " --sn %s") + |> appendIfSome parameters.SystemUnderTestVersion (sprintf " --sv %s") + |> appendIfSome parameters.FeatureFileLanguage (sprintf " -l %s") + |> appendWithoutQuotes (sprintf " --df %s" outputFormat) + |> appendIfSome testResultFormat (sprintf " --trfmt %s") + |> appendIfSome linkedResultFiles (sprintf " --lr %s") + |> 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 -> 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 +/// +/// ## Sample usage +/// +/// Target "BuildDoc" (fun _ -> +/// Pickles (fun p -> { p with +/// FeatureDirectory = currentDirectory @@ "Specs" +/// OutputDirectory = currentDirectory @@ "SpecDocs" }) +/// ) +let Pickles setParams = + traceStartTask "Pickles" "" + let parameters = setParams PicklesDefaults + let result = + ExecProcess (fun info -> + info.FileName <- parameters.ToolPath + info.WorkingDirectory <- "." + info.Arguments <- parameters |> buildPicklesArgs) parameters.TimeOut + + ResultHandling.failBuildIfPicklesReportedError parameters.ErrorLevel result + + traceEndTask "Pickles" "" \ No newline at end of file