Flutter自动生成README文档插件cli_readme_builder的使用

CLI README Builder

用于生成README文件的构建器。

概述

该软件包的目标是自动化创建Dart控制台应用程序的README文件的过程。

该软件包可以以两种方式使用：

1. build_runner -> 将其添加到pubspec.yaml的dev_dependencies中并运行build_runner
2. Dart可执行文件 -> 在Dart文件中实例化此类，并执行该Dart文件

在这两种情况下，该软件包都会生成一个包含应用程序中每个命令的--help输出的单个文件。

使用Build Runner生成README

步骤1：在pubspec.yaml中添加cli_readme_builder和build_runner

name: example_cli
dev_dependencies:
  build_runner: ^1.0.0
  cli_readme_builder: ^1.0.0

步骤2：运行构建

> dart pub run build_runner build

步骤3：生成README文件

README.g.md将被生成，其内容如下：

example_cli

Example CLI app

Usage

example_cli --help

Help output:

Example CLI app

Usage: example_cli <command> [arguments]

Global options:
-h, --help    Print this usage information.

Available commands:
child_command              Child Command description

Run "example_cli help <command>" for more information about a command.

Available commands

• child_command

child_command

example_cli child_command --help

Help output:

Child Command description

Usage: example_cli child_command [arguments]
-h, --help                                  Print this usage information.
   --option_arg=<value help for option>    An option argument
   --[no-]flag_arg                         A flag argument

Run "example_cli help" to see global options.

完整的示例输出可以在这里查看：[Example App Output](https://github.com/m-skolnick/cli_readme_builder/blob/main/example/example_output_file_from_cli.md)

#### 自定义生成路径

要更改生成文件的路径，可以在软件包的根目录中创建一个`build.yaml`文件。通过修改此构建器的`output`选项，可以自定义路径。

```yaml
targets:
  $default:
    builders:
      cli_readme_builder:
        options:
          output: my_output_file.md

高级功能

详细日志记录

为了使调试更容易，可以在build.yaml中添加verbose_logging选项。

targets:
  $default:
    builders:
      cli_readme_builder:
        options:
          verbose_logging: true

使用Dart可执行文件生成README

步骤1：在pubspec.yaml中添加cli_readme_builder到dev_dependencies

name: example_cli
dev_dependencies:
  cli_readme_builder: ^1.0.0

步骤2：创建一个Dart文件来执行此软件包

import 'package:cli_readme_builder/readme_builder_from_command_runner.dart';
import 'package:example/example_cli_command_runner.dart';

void main(List<String> args) {
  final myCommandRunner = ExampleCliCommandRunner();
  ReadmeBuilderFromCommandRunner(
    args,
    myCommandRunner,
  ).generateReadme();
}

步骤3：运行文件

dart run <path_to_my_file>

步骤4：生成README文件

README.g.md将被生成。

完整的示例输出可以在这里查看：Example App Output

自定义生成路径

要更改生成文件的路径，可以在执行时传递output选项。

dart run <path_to_my_file> --output <my_new_output_file>

维护者

• Micaiah Skolnick

示例代码

示例文件夹中的README.md

A simple command-line application which demonstrates how to use cli_readme_builder

注意以下几点：

1. example_cli_command_runner

   • 这是一个使用默认Dart Command Runner的简单命令行应用程序。

2. pubspec.yaml

   • 包含cli_readme_builder和build_runner

3. build.yaml

   • 覆盖默认输出文件

4. my_output_file.md

   • 这是生成的输出README文件

   生成此文件，运行：

   dart run build_runner build --delete-conflicting-outputs