How to document the documentation of cake assembly arguments?

Question

In the script cake assembly, there is a very clear way to document tasks using the .Description() extension in Task. These descriptions are displayed when the script assembly is invoked with the -showdescription argument.

I have a few user arguments in my build script that I would like to document somehow. Currently, I have added a task that displays description text similar to a manual page style for available arguments, which looks something like this:

 var nextLineDescription = "\n\t\t\t\t\t"; // for formatting Console.WriteLine("ARGUMENTS"); Console.WriteLine(""); Console.WriteLine("\t--someparameter=<number>\t\t" + "Description of the parameter" + nextLineDescription + "that can span multiple lines" + nextLineDescription + "and defaults to 5.\n"); 

This works great, but it's a lot of work, especially if the text needs to be formatted correctly, so it is read on the command line.

So when I call ./build.ps1 -Target MyDocTask I get a nice result:

  ARGUMENTS

         --someparameter = number Description of the parameter
                                         that can span multiple lines
                                         and defaults to 5

         --nextParameter Next description

 ...

Is there any other way, or best practice, to add documentation for the arguments so that it appears on the command line, similar to the task description?

Edit: Alternatively, can I find all the available parameters in my script assembly to cyclize them and generate such a description instead of writing it manually for each parameter?

Answer 1

There is currently no built-in function for "registering" arguments for reference, it would be a great addition, so please raise a question about this.

To say that this can be achieved since Cake is just .NET. You can use one of the command line parsers available on NuGet to achieve this. One such parser is CommandLineParser .

Assemblies can be links from NuGet using the #addin directive, for CommandLineParser it looks below

 #addin "nuget:?package=CommandLineParser&version=2.1.1-beta&prerelease=true" 

Since this is not a "native" Cake addin, you will need to use fully qualified type names, or just like normal C # add a using statement like this

 using CommandLine; 

CommandLineParser uses the class and property attributes to provide rules and help. Porting your example below will look something like

 class Options { [Option("someparameter", HelpText = "Description of the parameter, that can span multiple lines", Default = 5)] public int SomeParameter { get; set; } [Option("nextParameter", HelpText = "Next description")] public string NextParameter { get; set; } [Option("target", HelpText = "Target", Default = "Default")] public string Target { get; set; } } 

CommandLineParser usually displays help on the console, but if you want to display it in a task, you can write the output using TextWriter

 var helpWriter = new StringWriter(); var parser = new Parser(config => config.HelpWriter = helpWriter); 

Then by parsing the arguments, and if "MyDocTask" is specified, help make helpWriter

 Options options = parser .ParseArguments<Options>( StringComparer.OrdinalIgnoreCase.Equals(Argument("target", "Default"), "MyDocTask") ? new []{ "--help" } : System.Environment.GetCommandLineArgs() ) .MapResult( o => o, errors=> new Options { Target = "MyDocTask"} // TODO capture errors here ); 

and tasks

 Task("MyDocTask") .Does(() => { Information(helpWriter.ToString()); } ); Task("Default") .Does(() => { Information("SomeParameter: {0}", options.SomeParameter); Information("NextParameter: {0}", options.NextParameter); Information("Target: {0}", options.Target); } ); 

then executed

 RunTarget(options.Target); 

MyDocTask will display help

 >> cake .\commandline.cake --Target="MyDocTask" ======================================== MyDocTask ======================================== Cake 0.20.0+Branch.main.Sha.417d1eb9097a6c71ab25736687162c0f58bbb74a Copyright (c) .NET Foundation and Contributors --someparameter (Default: 5) Description of the parameter, that can span multiple lines --nextParameter Next description --target (Default: Default) Target --help Display this help screen. --version Display version information. 

and Default task will simply display the values ​​of the parsed arguments

 >> cake .\commandline.cake ======================================== Default ======================================== SomeParameter: 5 NextParameter: [NULL] Target: Default Task Duration -------------------------------------------------- Default 00:00:00.0133265 -------------------------------------------------- Total: 00:00:00.0133265 

This will give you strongly typed and documented arguments in a fairly simple way.

Full cake script below:

 #addin "nuget:?package=CommandLineParser&version=2.1.1-beta&prerelease=true" using CommandLine; class Options { [Option("someparameter", HelpText = "Description of the parameter, that can span multiple lines", Default = 5)] public int SomeParameter { get; set; } [Option("nextParameter", HelpText = "Next description")] public string NextParameter { get; set; } [Option("target", HelpText = "Target", Default = "Default")] public string Target { get; set; } } var helpWriter = new StringWriter(); var parser = new Parser(config => config.HelpWriter = helpWriter); Options options = parser .ParseArguments<Options>( StringComparer.OrdinalIgnoreCase.Equals(Argument("target", "Default"), "MyDocTask") ? new []{ "--help" } : System.Environment.GetCommandLineArgs() ) .MapResult( o => o, errors=> new Options { Target = "MyDocTask"} // could capture errors here ); Task("MyDocTask") .Does(() => { Information(helpWriter.ToString()); } ); Task("Default") .Does(() => { Information("SomeParameter: {0}", options.SomeParameter); Information("NextParameter: {0}", options.NextParameter); Information("Target: {0}", options.Target); } ); RunTarget(options.Target);