Flutter文档辅助插件readme_helper的使用

帮助生成README及其他Markdown文件的代码工具。

快速开始

1. 安装或更新 readme_helper:

flutter pub global activate readme_helper

2. 开始使用这些“神奇”的注释命令：

插入外部文件的代码示例:
<!-- #code path/to/file.dart -->

基于使用的标题创建目录:
<!-- #toc -->

这将包含另一个Markdown文件:
<!-- #include path/to/other_markdown.md -->

3. 运行 readme_helper 处理当前项目:

flutter pub global run readme_helper

目录

• 快速开始
• 动机
• 用法
• 命令

动机

良好的文档是连接包创建者和开发者的钥匙。

嵌入代码示例至关重要，但它们可能会过时。 此工具允许你使用外部代码文件，正确性由你的IDE确保。

其他工具如Markdown文件的包含或目录生成，将帮助你节省时间。

用法

readme_helper 是一个Dart应用，可以通过以下命令安装或更新：

flutter pub global activate readme_helper

你可以通过以下命令运行 readme_helper：

flutter pub global run readme_helper

它会处理当前目录及其子目录内的所有Markdown文件。

你也可以单独处理一个文件：

flutter pub global run readme_helper path/to/file.md

命令

你可以在Markdown文件中通过HTML注释指定命令。每个 readme_helper 命令以 # 开头：

<!-- #command argument -->

代码嵌入

你可以通过定义相对路径来嵌入外部文件：

<!-- #code path/to/code.dart -->

这将在文件中添加该文件的内容作为代码块。

范围注释

你可以使用注释来控制要显示的外部文件部分。

import 'dart:math';

// #begin
class MyClass {
  // #skip
  int someMethod() {
    return Random().nextInt(1);
  }
  // #resume

  String interestingMethod() {
    return 'Foo';
  }
}
// #end

这将添加以下代码块：

class MyClass {
  ...

  String interestingMethod() {
    return 'Foo';
  }
}

缩进

通过缩进 // #begin 范围注释，可以提示移除前导空白。

class AnotherClass {
  // #begin
  int importantMethod() {
    return 42;
  }
  // #end
}

这将添加以下代码块：

int importantMethod() {
  return 42;
}

目录生成

readme_helper 将扫描所有的Markdown标题（## 和 ###）并生成目录。

# project_name

<!-- #toc -->

## chapter a
### section 1
### section 2

## chapter b
### section 3
### section 4

这将创建类似以下的内容：

• chapter a
  • section 1
  • section 2
• chapter b
  • section 3
  • section 4

包含Markdown文件

你可以通过使用包含命令，将其他文件的部分内容包含到当前Markdown文件中：

<!-- #include path/to/part.md -->

生成换行符

默认情况下，你不能有超过一个新行。为了美观，你可能希望扩展这个限制。

<!-- #space 2 -->

这将使用   字符生成换行符。

示例

假设我们有一个名为 example.md 的Markdown文件，其内容如下：

# Project README

<!-- #toc -->

## Introduction
This is the introduction.

<!-- #code path/to/example_code.dart -->

## Usage
Here is how to use it.

<!-- #include path/to/another_part.md -->

## Conclusion
This is the conclusion.

其中 example_code.dart 文件内容如下：

import 'dart:math';

// #begin
class MyClass {
  // #skip
  int someMethod() {
    return Random().nextInt(1);
  }
  // #resume

  String interestingMethod() {
    return 'Foo';
  }
}
// #end

another_part.md 文件内容如下：

## Advanced Usage
This is advanced usage.

运行 readme_helper 后，example.md 文件将被处理为：

# Project README

- [Introduction](#introduction)
- [Usage](#usage)
- [Conclusion](#conclusion)

## Introduction
This is the introduction.

```dart
class MyClass {
  ...

  String interestingMethod() {
    return 'Foo';
  }
}

Usage

Here is how to use it.

Advanced Usage

This is advanced usage.

Conclusion

This is the conclusion.