Flutter代码生成文档插件code2docs的使用

Flutter代码生成文档插件code2docs的使用

定义逐步示例

要使用code2docs生成逐步示例的文档，首先需要创建一个包含最终代码的源文件。例如：

void main() {
    print('hello,');
    print('world');
    print('The end.');
}

在文件的开头，定义示例代码的标题和步骤列表：

// TITLE: 这是示例代码。
// STEPS:
// 1: 打印 hello。
// 2: 打印 world。
// 3: 描述步骤 3。

使用特定的注释来分隔属于特定步骤的代码块的开始部分：

void main() {
    //>step:1 在 main 的开头添加此内容。
    print('hello,');
    //>step:2 在 `print('hello,');` 之后添加此内容。
    print('world');
    //>step:3 描述是可选的。
    print('The end.');
}

使用特定的注释来分隔属于特定步骤的代码块的结束部分：

void main() {
    //>step:1 在 main 的开头添加此内容。
    print('hello,');
    //<step:1
    //>step:2 在 `print('hello,');` 之后添加此内容。
    print('world');
    //<step:2
    //>step:3 描述是可选的。
    print('The end.');
    //<step:3    
}

使用此库

使用code2docs生成Markdown文档的示例代码如下：

import 'package:code2docs/code2docs.dart';

void main() {
    final generator = SourceCodeSampleToMarkdown(language: 'dart');
    final markdown = generator.generate(_sourceCode);
    print(markdown);
}

final _sourceCode =
    """
// TITLE: 创建测试
// STEPS:
// 1: 导入测试包。
// 2: 创建主函数。
// 3: 创建测试组。
// 4: 创建测试方法。
//>step:1
import 'package:test/test.dart';
//<step:1
//>step:2
  void main() {
    //>step:3 在主函数中添加此内容。
    group('我的测试组', () {
      //>step:4 在测试组中添加此内容。
      test('我的测试方法', () {

      });
      //<step:4
    });
    //<step:3
  }
//<step:2
    """;

示例代码

以下是一个完整的示例代码，展示了如何使用code2docs生成逐步示例的文档。

import 'package:code2docs/code2docs.dart';

void main() {
    final generator = SourceCodeSampleToMarkdown(language: 'dart');

    final markdown = generator.generate(_sourceCode);

    print(markdown);
}

final _sourceCode =
    """
// TITLE: 创建一个测试
// STEPS:
// 1: 导入测试包。
// 2: 创建主函数。
// 3: 创建测试组。
// 4: 创建测试方法。
//>step:1
import 'package:test/test.dart';
//<step:1
//>step:2
  void main() {
    //>step:3 在主函数中添加此内容。
    group('我的测试组', () {
      //>step:4 在测试组中添加此内容。
      test('我的测试方法', () {

      });
      //<step:4
    });
    //<step:3
  }
//<step:2
    """;