Flutter文档生成插件documentation_builder的使用

插件简介

documentation_builder 是一个用于从Markdown模板文件生成Markdown文档文件的插件。它可以帮助你在编写Dart或Flutter项目的文档时，复用或导入Dart代码或Dart文档注释。该插件可以生成以下类型的文件：

• ReadMeFile：项目说明文件
• ChangeLogFile：变更日志文件
• ExampleFile：示例文件
• GitHub WikiTemplateFile：GitHub Wiki页面

需要注意的是，documentation_builder 并不适用于生成API文档，推荐使用 dartdoc 来生成API文档。

使用示例

documentation_builder 自身的文档就是通过该插件生成的，因此可以作为一个很好的示例。你可以查看模板文件和生成的输出：

README 文件

• Markdown 模板文件：README.mdt
• 生成的 Markdown 文件（原始）：README.md
• 生成的 Markdown 文件（渲染后）：README

LICENSE 文件

• Markdown 模板文件：LICENSE.mdt
• 生成的 Markdown 文件（原始）：LICENSE

CHANGELOG 文件

• Markdown 模板文件：CHANGELOG.mdt
• 生成的 Markdown 文件（原始）：CHANGELOG.md
• 生成的 Markdown 文件（渲染后）：CHANGELOG

Wiki 页面

• Markdown 模板文件：WikiTemplateFiles
• 生成的 Markdown 文件（渲染后）：Wiki

示例文件

• Markdown 模板文件：example.mdt
• 生成的 Markdown 文件（原始）：example.md
• 生成的 Markdown 文件（渲染后）：example

快速开始

以下是使用 documentation_builder 的步骤：

1. 阅读文档：参考 Wiki 文档 了解详细信息。
2. 安装插件：在你的项目中安装 documentation_builder 包：

   dependencies:
     documentation_builder: ^latest_version
   

3. 配置 build.yaml 文件：在项目根目录下添加 build.yaml 文件，并添加以下内容（如果 build.yaml 文件已存在，请合并内容）：

   targets:
     $default:
       sources:
         - doc/**
         - lib/**
         - bin/**
         - test/**
         - pubspec.*
         - $package$
   

4. 创建模板目录：在项目根目录下创建 doc/template 目录。
5. 创建Markdown模板文件：在 doc/template 目录中创建Markdown模板文件，参考 模板文件示例。
6. 生成文档文件：运行以下命令生成文档文件：

   flutter pub run build_runner build
   

7. 发布文档文件：将生成的文档文件发布到你选择的平台（如GitHub、Pub等）。

完整示例Demo

以下是一个完整的示例项目结构和配置，展示了如何使用 documentation_builder 生成文档：

项目结构

my_flutter_project/
├── doc/
│   └── template/
│       ├── README.mdt
│       ├── LICENSE.mdt
│       ├── CHANGELOG.mdt
│       └── example.mdt
├── lib/
│   └── main.dart
├── build.yaml
└── pubspec.yaml

pubspec.yaml

name: my_flutter_project
description: A new Flutter project.
publish_to: 'none' # Remove this line if you wish to publish the package
version: 1.0.0+1

environment:
  sdk: ">=2.12.0 <3.0.0"

dependencies:
  flutter:
    sdk: flutter
  documentation_builder: ^latest_version

dev_dependencies:
  flutter_test:
    sdk: flutter
  build_runner: ^2.0.0
  markdown: ^4.0.0

flutter:
  uses-material-design: true

build.yaml

targets:
  $default:
    sources:
      - doc/**
      - lib/**
      - bin/**
      - test/**
      - pubspec.*
      - $package$

doc/template/README.mdt

My Flutter Project

This is a simple Flutter project that demonstrates how to use documentation_builder.

Getting Started

To get started, follow these steps:

1. Clone the repository.
2. Run flutter pub get.
3. Run flutter pub run build_runner build to generate the documentation.
4. Open the generated README.md file.

Features

• Feature 1
• Feature 2
• Feature 3

Example Code

import 'package:flutter/material.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'My Flutter App',
      home: Scaffold(
        appBar: AppBar(
          title: Text('My Flutter App'),
        ),
        body: Center(
          child: Text('Hello, World!'),
        ),
      ),
    );
  }
}

#### `doc/template/LICENSE.mdt`

MIT License

Copyright (c) 2023 Your Name

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

doc/template/CHANGELOG.mdt

Changelog

All notable changes to this project will be documented in this file.

[1.0.0] - 2023-10-01

• Initial release of the project.
• Added basic features.
• Generated documentation using documentation_builder.

#### `doc/template/example.mdt`

# Example

This is an example of how to use `documentation_builder` to generate documentation for your Flutter project.

## Example Code

```dart
import 'package:flutter/material.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Example App',
      home: Scaffold(
        appBar: AppBar(
          title: Text('Example App'),
        ),
        body: Center(
          child: Text('This is an example!'),
        ),
      ),
    );
  }
}

生成文档

在项目根目录下运行以下命令来生成文档：

flutter pub run build_runner build