Làm cách nào để có thể lập hồ sơ xây dựng bánh?

Question

Trong một kịch bản xây dựng bánh có một cách rất gọn gàng để ghi lại các tác vụ bằng cách sử dụng phần mở rộng .Description() trên Tác vụ. Các mô tả này được hiển thị khi gọi tập lệnh xây dựng với đối số -showdescription.

Tôi có một số đối số tùy chỉnh trong tập lệnh xây dựng của mình mà tôi muốn tài liệu bằng cách nào đó. Hiện nay tôi đã thêm một nhiệm vụ mà kết quả đầu ra một văn bản mô tả giống với manual page style cho các đối số có sẵn mà trông giống như sau:

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"); 

này hoạt động tốt nhưng là rất nhiều công việc, đặc biệt là nếu văn bản nên được định dạng đúng như vậy nó có thể đọc được trong dòng lệnh.

Vì vậy, khi tôi gọi ./build.ps1 -Target MyDocTask tôi nhận được một kết quả tốt đẹp:

 
ARGUMENTS 

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

     --nextParameter     Next description 

... 

Có một cách khác hay một thực hành tốt nhất để thêm tài liệu hướng dẫn cho các đối số để nó có thể được hiển thị trong dòng lệnh tương tự như nhiệm vụ mô tả?

Chỉnh sửa: Ngoài ra, tôi có thể tìm tất cả các tham số sẵn có trong kịch bản xây dựng của mình để lặp qua chúng và tạo mô tả như vậy thay vì viết nó theo cách thủ công cho từng thông số không?

Answer 1

Hiện tại không có tính năng tích hợp cho các đối số "đăng ký" để được trợ giúp, sẽ là một bổ sung tuyệt vời mặc dù vậy vui lòng nêu ra vấn đề về điều đó.

Điều đó nói rằng nó có thể đạt được, vì Bánh chỉ là .NET. Bạn có thể sử dụng một trong các trình phân tích cú pháp dòng lệnh có sẵn trên NuGet để đạt được điều này. Một trình phân tích cú pháp như vậy là CommandLineParser.

Assemblies có thể tham khảo từ NuGet bằng cách sử dụng chỉ thị #addin, cho CommandLineParser có vẻ dưới

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

Vì nó không phải là một "bản địa" Bánh addin bạn sẽ cần phải sử dụng đầy đủ tên loại hoặc giống như bình thường C# thêm tuyên bố sử dụng như thế này

using CommandLine; 

CommandLineParser sử dụng lớp và thuộc tính về thuộc tính để cung cấp quy tắc và trợ giúp.Porting dụ của bạn dưới đây sẽ giống như dưới đây

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; } 
} 

thường CommandLineParser sẽ ra giúp đỡ để giao diện điều khiển, nhưng nếu bạn muốn hiển thị nó trong một nhiệm vụ, bạn có thể bắt đầu ra với một TextWriter

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

luận Sau đó phân tích và nếu "MyDocTask" được quy định làm giúp đỡ để các 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 
); 

và nhiệm vụ

Task("MyDocTask") 
    .Does(() => { 
     Information(helpWriter.ToString()); 
} 
); 

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

sau đó thực hiện

RunTarget(options.Target); 

Các MyDocTask chí ra sự giúp đỡ

>> 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. 

và Default nhiệm vụ sẽ giá trị chỉ ra những lập luận phân tích cú pháp

>> cake .\commandline.cake 

======================================== 
Default 
======================================== 
SomeParameter: 5 
NextParameter: [NULL] 
Target: Default 

Task       Duration 
-------------------------------------------------- 
Default      00:00:00.0133265 
-------------------------------------------------- 
Total:      00:00:00.0133265 

Thị s sẽ cung cấp cho bạn các đối số được đánh máy và ghi tài liệu một cách khá dễ dàng.

Kịch bản Bánh hoàn toàn dưới đây:

#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);