Flutter文档生成插件dartdoc的使用

Dart文档生成器dartdoc是用于为Dart包生成HTML文档的强大工具。它可以帮助开发者创建清晰、易于导航和搜索的API文档。以下是关于如何安装、配置和使用dartdoc的详细指南。

安装

dartdoc是Dart SDK的一部分，因此您只需要安装Dart SDK即可。请参考Dart官网获取安装指南。

生成文档

要为您的Dart包生成文档，请按照以下步骤操作：

1. 确保依赖项已获取：在项目根目录下运行dart pub get或flutter pub get。
2. 确保代码无误：使用dart analyze或flutter analyze检查代码是否有错误。
3. 生成文档：在项目根目录下运行dart doc .。

例如：

$ dart pub get
...
$ dart doc .
Documenting dartdoc...
...
Initialized dartdoc with 766 libraries in 63.9 seconds
Generating docs for library dartdoc from package:dartdoc/dartdoc.dart...
Validating docs...
no issues found
Documented 1 public library in 17.9 seconds
Success! Docs generated into <path to dartdoc>/doc/api

默认情况下，生成的文档会保存在项目的doc/api目录中。

查看文档

为了启用导航和搜索功能，您需要通过HTTP服务器来查看生成的文档。可以使用dhttpd包轻松设置本地HTTP服务器：

$ dart pub global activate dhttpd
$ dart pub global run dhttpd --path doc/api

然后，在浏览器中打开dhttpd输出的链接，通常是http://localhost:8080。

配置选项

您可以创建一个名为dartdoc_options.yaml的文件来自定义dartdoc的行为。以下是一个示例配置文件：

dartdoc:
  categories:
    "First Category":
      markdown: doc/First.md
      name: Awesome
    "Second Category":
      markdown: doc/Second.md
      name: Great
  categoryOrder: ["First Category", "Second Category"]
  includeExternal: ['bin/unusually_located_library.dart']
  nodoc: ['lib/sekret/*.dart']
  linkTo:
    url: "https://my.dartdocumentationsite.org/dev/%v%"
  showUndocumentedCategories: true
  ignore:
    - ambiguous-doc-reference
  errors:
    - unresolved-doc-reference
  warnings:
    - tool-error

此文件中的路径应为POSIX格式，并且是相对于dartdoc_options.yaml文件所在的目录。支持的选项包括但不限于：

• categories: 定义文档分类。
• categoryOrder: 指定分类显示顺序。
• exclude: 排除某些库的文档生成。
• errors: 将某些警告提升为错误。
• favicon: 设置生成文档的favicon。
• footer: 添加页脚内容。
• header: 添加页眉内容。
• include: 包含特定库的文档生成。
• linkTo: 控制生成文档的链接地址。
• nodoc: 排除特定文件的文档生成。
• warnings: 设置警告级别。

示例代码

下面是一个简单的Flutter项目，展示了如何使用dartdoc生成文档。

项目结构

example_project/
├── lib/
│   └── main.dart
├── doc/
│   ├── First.md
│   └── Second.md
└── dartdoc_options.yaml

main.dart

/// Here is my library.
///
/// {@category Awesome}
library example_project;

import 'package:flutter/material.dart';

/// A simple widget that displays a greeting message.
///
/// {@category Basics}
/// {@category Widgets}
class GreetingWidget extends StatelessWidget {
  final String message;

  /// Creates a [GreetingWidget] with the specified [message].
  const GreetingWidget({Key? key, required this.message}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Center(
      child: Text(message),
    );
  }
}

void main() {
  runApp(MaterialApp(
    home: Scaffold(
      appBar: AppBar(title: Text('Example Project')),
      body: GreetingWidget(message: 'Hello, World!'),
    ),
  ));
}

dartdoc_options.yaml

dartdoc:
  categories:
    "Awesome":
      markdown: doc/First.md
      name: Awesome Features
    "Basics":
      markdown: doc/Second.md
      name: Basic Components
  categoryOrder: ["Awesome", "Basics"]
  linkTo:
    url: "https://example.com/docs/%v%"

生成并查看文档

1. 获取依赖：

   $ dart pub get
   

2. 生成文档：

   $ dart doc .
   

3. 启动HTTP服务器：

   $ dart pub global activate dhttpd
   $ dart pub global run dhttpd --path doc/api
   

4. 访问文档： 打开浏览器并访问http://localhost:8080。

通过以上步骤，您就可以成功地为您的Flutter项目生成并查看详细的API文档了。希望这些信息对您有所帮助！如果有任何问题，欢迎随时提问。