如何在Flutter项目DartDoc文档中正确嵌入渲染DartPad

• 正在使用DartDoc为Flutter应用内组件生成供同事参考的内部文档，目前基础文档展示功能已经正常跑通
• 需要借助Snippets包在文档中嵌入DartPad形式的可交互示例代码

当前编写的组件注释代码如下：

/// A basic button, which consists of a content, typically a text, in a filled container.
///
/// {@tool snippet}
/// TEST: Create snippet...
///
/// ```dart
/// CircleAvatar(
///   backgroundImage: NetworkImage(userAvatarUrl),
/// )
/// ```
/// {@end-tool}
///
/// {@tool dartpad}
/// TEST: Create dartpad snippet...
///
/// ** See code in examples/api/lib/widgets/atoms/button/button.0.dart **
/// {@end-tool}
class NeuButton extends StatelessWidget {

实际生成文档时，@tool标签无法按预期渲染，标签原文直接暴露在页面中，没有被解析为对应的示例组件。

曾按照如下规则编写dartdoc_options.yaml配置文件：

dartdoc:
  include: [Atoms, Components, Templates, Helpers]
  tools:
    snippet:
      command:
        [ 'bin/cache/dart-sdk/bin/dart', 'pub', 'global', 'run', 'snippets', '--output-directory=doc/snippets', '--type=snippet' ]
      description: 'Creates sample code documentation output from embedded documentation samples.'
    sample:
      command:
        [ 'bin/cache/dart-sdk/bin/dart', 'pub', 'global', 'run', 'snippets', '--output-directory=doc/snippets', '--type=sample' ]
      description: 'Creates full application sample code documentation output from embedded documentation samples.'
    dartpad:
      command:
        [ 'bin/cache/dart-sdk/bin/dart', 'pub', 'global', 'run', 'snippets', '--output-directory=doc/snippets', '--type=dartpad' ]
      description: 'Creates full application sample code documentation output from embedded documentation samples and displays it in an embedded DartPad.'

• 目前不确定配置中bin/cache/dart-sdk/bin/dart路径的正确写法，曾尝试直接从Flutter仓库复制bin文件夹到项目根目录，仍然无法解决标签渲染异常的问题
• 核心诉求：让snippet工具正常生效，尤其是{@tool dartpad}标签可以正确渲染出嵌入的DartPad示例。

运行dartdoc的完整操作步骤 #

• 执行flutter pub global activate dartdoc
• 执行dart pub global activate snippets
• 执行flutter pub global run dartdoc .
• 执行flutter pub global activate dhttpd
• 执行dhttpd --path doc/api启动本地文档服务

相关依赖版本 #

• dartdoc 5.1.2
• snippets 0.2.5
• dhttpd 4.0.1

flutter doctor -v 运行结果 #

[✓] Flutter (Channel stable, 2.10.4, on macOS 11.6.6 20G624 darwin-x64, locale en-ID)
    • Flutter version 2.10.4 at /Users/lpt530/Library/Flutter
    • Upstream repository https://github.com/flutter/flutter.git
    • Framework revision c860cba910 (2 months ago), 2022-03-25 00:23:12 -0500
    • Engine revision 57d3bac3dd
    • Dart version 2.16.2
    • DevTools version 2.9.2

[✓] Android toolchain - develop for Android devices (Android SDK version 30.0.3)
    • Android SDK at /Users/lpt530/Library/Android/sdk
    • Platform android-31, build-tools 30.0.3
    • ANDROID_HOME = /Users/lpt530/Library/Android/sdk
    • Java binary at: /Applications/Android Studio.app/Contents/jre/Contents/Home/bin/java
    • Java version OpenJDK Runtime Environment (build 11.0.12+0-b1504.28-7817840)
    • All Android licenses accepted.

[!] Xcode - develop for iOS and macOS (Xcode 12.5.1)
    • Xcode at /Applications/Xcode.app/Contents/Developer
    ! Flutter recommends a minimum Xcode version of 13.
      Download the latest version or update via the Mac App Store.
    • CocoaPods version 1.10.1

[✓] Chrome - develop for the web
    • Chrome at /Applications/Google Chrome.app/Contents/MacOS/Google Chrome

[✓] Android Studio (version 2021.2)
    • Android Studio at /Applications/Android Studio.app/Contents
    • Flutter plugin can be installed from:
      🔨 https://plugins.jetbrains.com/plugin/9212-flutter
    • Dart plugin can be installed from:
      🔨 https://plugins.jetbrains.com/plugin/6351-dart
    • Java version OpenJDK Runtime Environment (build 11.0.12+0-b1504.28-7817840)

[✓] VS Code (version 1.67.2)
    • VS Code at /Applications/Visual Studio Code.app/Contents
    • Flutter extension version 3.42.0

[✓] Connected device (2 available)
    • macOS (desktop) • macos  • darwin-x64     • macOS 11.6.6 20G624 darwin-x64
    • Chrome (web)    • chrome • web-javascript • Google Chrome 102.0.5005.61

[✓] HTTP Host Availability
    • All required HTTP hosts are available

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