如何使用dartdoc生成类似docs.flutter.io的Flutter文档？

我刚好研究过这个问题，其实dartdoc本身就可以生成和docs.flutter.io风格一致的Flutter文档，只是需要加上一些特定参数配置，下面一步步来操作：

• 第一步：先确保你的Flutter项目依赖都拉取完整，在项目根目录运行：

  flutter pub get
  

  这一步能保证所有Flutter核心库（比如material、cupertino）的源码和注释都能被dartdoc识别到。

• 第二步：使用带参数的dartdoc命令生成文档，完整命令如下：

  dartdoc --dart-sdk=${FLUTTER_ROOT}/bin/cache/dart-sdk --include-external --theme flutter
  

  这里给你解释下关键参数的作用：

  • --dart-sdk：指定Flutter自带的Dart SDK路径，因为Flutter的核心库源码都在这个SDK目录里，dartdoc需要它来解析Flutter的API注释
  • --include-external：允许包含项目外部的依赖库（也就是Flutter官方的那些核心库），不然只会生成你自己项目的代码文档
  • --theme flutter：启用Flutter官方的文档主题，这就是生成docs.flutter.io风格的核心配置

• 第三步（可选）：如果想指定文档的输出目录，比如放到项目根目录的docs文件夹里，可以加上--output参数：

  dartdoc --output docs --dart-sdk=${FLUTTER_ROOT}/bin/cache/dart-sdk --include-external --theme flutter
  

一些注意事项 #

• 如果你不知道FLUTTER_ROOT的具体路径，可以运行flutter doctor -v，在输出里找到Flutter SDK的安装路径，手动替换命令里的${FLUTTER_ROOT}部分
• 生成过程中如果出现警告，大概率是项目里的代码注释不符合dartdoc规范，记得用///开头来写文档注释，而不是//或者/** */
• 生成完成后，打开输出目录里的index.html，就能看到和docs.flutter.io风格完全一致的文档了

内容的提问来源于stack exchange，提问作者Creatint