Allow ref version for doc generation

This commit allows a reference version to be passed when generating documentation. The reference version is the version used in the link to the Elasticsearch reference documentation.

(cherry picked from commit eea3887)

Author: russcam

build/scripts/Commandline.fs

@@ -44,6 +44,7 @@ Execution hints can be provided anywhere on the command line
 - gendocs : generate documentation
 - non-interactive : make targets that run in interactive mode by default to run unassisted.
 - docs:<B> : the branch name B to use when generating documentation
+- ref:<B> : the reference version B to use when generating documentation
 - seed:<N> : provide a seed to run the tests with.
 - random:<K><:B> : sets random K to bool B if if B is omitted will default to true
   K can be: sourceserializer, typedkeys or oldconnection (only valid on windows)
@@ -95,6 +96,7 @@ Execution hints can be provided anywhere on the command line
         Seed: string;
         RandomArguments: string list;
         DocsBranch: string;
+        ReferenceBranch: string;
         RemainingArguments: string list;
         MultiTarget: MultiTarget;
         Target: string;
@@ -123,7 +125,8 @@ Execution hints can be provided anywhere on the command line
                x <> "non-interactive" && 
                not (x.StartsWith("seed:")) && 
                not (x.StartsWith("random:")) && 
-               not (x.StartsWith("docs:")))
+               not (x.StartsWith("docs:")) &&
+               not (x.StartsWith("ref:")))
         let target = 
             match (filteredArgs |> List.tryHead) with
             | Some t -> t.Replace("-one", "")
@@ -146,6 +149,10 @@ Execution hints can be provided anywhere on the command line
                 match args |> List.tryFind (fun x -> x.StartsWith("docs:")) with
                 | Some t -> t.Replace("docs:", "")
                 | _ -> ""
+            ReferenceBranch = 
+                match args |> List.tryFind (fun x -> x.StartsWith("ref:")) with
+                | Some t -> t.Replace("ref:", "")
+                | _ -> ""
             RemainingArguments = filteredArgs
             MultiTarget = 
                 match (filteredArgs |> List.tryHead) with

build/scripts/Documentation.fs

@@ -4,15 +4,27 @@ open System.IO
 
 open Projects
 open Commandline
+open Fake.Core
 
 module Documentation = 
 
     let Generate args = 
         let docGenerator = PrivateProject(DocGenerator)
         let path = Paths.ProjectOutputFolder docGenerator DotNetFramework.NetCoreApp2_1
-        let generator = sprintf "%s.dll" docGenerator.Name 
+        let generator = sprintf "%s.dll" docGenerator.Name
 
-        Tooling.DotNet.ExecIn path [generator; args.DocsBranch] |> ignore
+        let (|NotNullOrEmpty|_|) (candidate:string) =
+            if String.isNotNullOrEmpty candidate then Some candidate
+            else None
+        
+        let dotnetArgs =     
+            match (args.DocsBranch, args.ReferenceBranch) with
+            | (NotNullOrEmpty b, NotNullOrEmpty d) -> [ generator; "-b"; b; "-d"; d ];
+            | (NotNullOrEmpty b, _) -> [ generator; "-b"; b ];
+            | (_, NotNullOrEmpty d) -> [ generator; "-d"; d ];
+            | (_, _) -> [ generator ]
+        
+        Tooling.DotNet.ExecIn path dotnetArgs |> ignore
 
     // TODO: hook documentation validation into the process
     let Validate() = 

src/CodeGeneration/DocGenerator/DocGenerator.csproj

@@ -10,6 +10,7 @@
   </PropertyGroup>
   <ItemGroup>
     <PackageReference Include="AsciiDocNet" Version="1.0.0-alpha6" />
+    <PackageReference Include="CommandLineParser" Version="2.6.0" />
     <PackageReference Include="Microsoft.Build.Runtime" Version="15.7.179" />
     <PackageReference Include="Microsoft.Extensions.Logging" Version="1.1.2" />
     <PackageReference Include="Newtonsoft.Json" Version="12.0.1" />

src/CodeGeneration/DocGenerator/Program.cs

@@ -3,6 +3,7 @@
 using System.IO;
 using System.Linq;
 using System.Text.RegularExpressions;
+using CommandLine;
 
 namespace DocGenerator
 {
@@ -38,7 +39,7 @@ string P(string path)
 										 .Last().Value
 										 .Split(".")
 										 .Take(2));
-			Console.WriteLine("Using global.json version: " + globalJsonVersion);
+
 			DocVersion = globalJsonVersion;
 
 			var process = new Process
@@ -88,22 +89,41 @@ string P(string path)
 
 		private static int Main(string[] args)
 		{
-			try
-			{
-				if (args.Length > 0)
-					BranchName = args[0];
+			return Parser.Default.ParseArguments<DocGeneratorOptions>(args)
+				.MapResult(
+					opts =>
+					{
+						try
+						{
+							if (!string.IsNullOrEmpty(opts.BranchName))
+								BranchName = opts.BranchName;
 
-				Console.WriteLine($"Using branch name {BranchName} in documentation");
+							if (!string.IsNullOrEmpty(opts.DocVersion))
+								DocVersion = opts.DocVersion;
 
-				LitUp.GoAsync(args).Wait();
-				return 0;
-			}
-			catch (AggregateException ae)
-			{
-				var ex = ae.InnerException ?? ae;
-				Console.WriteLine(ex.Message);
-				return 1;
-			}
+							Console.WriteLine($"Using branch name {BranchName} in documentation");
+							Console.WriteLine($"Using doc reference version {DocVersion} in documentation");
+
+							LitUp.GoAsync(args).Wait();
+							return 0;
+						}
+						catch (AggregateException ae)
+						{
+							var ex = ae.InnerException ?? ae;
+							Console.WriteLine(ex.Message);
+							return 1;
+						}
+					},
+					errs => 1);
 		}
 	}
+
+	public class DocGeneratorOptions
+	{
+		[Option('b', "branch", Required = false, HelpText = "The version that appears in generated from source link")]
+		public string BranchName { get; set; }
+
+		[Option('d', "docs", Required = false, HelpText = "The version that links to the Elasticsearch reference documentation")]
+		public string DocVersion { get; set; }
+	}
 }