Как можно документировать аргументы построения торта?

Question

В скрипте сборки торта есть очень аккуратный способ документирования задач с использованием .Description() расширение на задание. Эти описания отображаются при вызове сценария сборки с -showdescription аргумент.

У меня есть несколько пользовательских аргументов в моем скрипте сборки, которые я хотел бы как-то задокументировать. В настоящее время я добавил задачу, которая выводит текст описания, аналогичный стилю страницы руководства, для доступных аргументов, который выглядит примерно так:

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

Это прекрасно работает, но много работы, особенно если текст должен быть правильно отформатирован, чтобы его можно было прочитать в командной строке.

Поэтому, когда я звоню ./build.ps1 -Target MyDocTaskЯ получаю хороший результат:

АРГУМЕНТЫ

        --someparameter= число Описание параметра
                                        которые могут занимать несколько строк
                                        и по умолчанию 5

        --nextParameter Следующее описание...

Есть ли другой способ или лучший способ добавить документацию для аргументов, чтобы она могла отображаться в командной строке подобно описаниям задач?

Изменить: В качестве альтернативы, могу ли я найти все доступные параметры в моем скрипте сборки, чтобы зациклить их и сгенерировать такое описание вместо того, чтобы писать его вручную для каждого параметра?

Answer 1

В настоящее время нет встроенной функции для "регистрации" аргументов для помощи, было бы отличным дополнением, поэтому, пожалуйста, поднимите вопрос об этом.

Тем не менее, этого можно достичь, поскольку Cake - это просто.NET, для этого можно использовать один из анализаторов командной строки, доступных в NuGet. Одним из таких парсеров является CommandLineParser.

Сборки могут быть ссылками от NuGet с использованием #addin директива, для CommandLineParser это выглядит ниже

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

Поскольку это не "родной" Cake-плагин, вам нужно использовать полные имена типов или просто как в обычном C# добавить оператор using, как этот

using CommandLine;

CommandLineParser использует класс и атрибуты в свойствах для предоставления правил и справки. Портирование вашего примера ниже будет выглядеть примерно так

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 выводит справку на консоль, но если вы хотите отобразить ее в задаче, вы можете захватить вывод с помощью TextWriter

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

Затем синтаксический анализ аргументов и, если указано "MyDocTask", оказать помощь 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
);

и задачи

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

MyDocTask выведет помощь

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

а также Default задача будет просто выводить значения проанализированных аргументов

>> cake .\commandline.cake

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

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

Это даст вам строго типизированные и документированные аргументы довольно простым способом.

Полный скрипт Cake ниже:

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