Doc snippets: Link to relevant dartdoc page

docs/build.deploy.yaml

@@ -1,54 +0,0 @@
-builders:
-  versions:
-    import: 'tool/write_versions.dart'
-    build_to: cache
-    builder_factories: ["writeVersions"]
-    build_extensions: {"$package$": ["lib/versions.json"]}
-  code_snippets:
-    import: 'tool/snippets.dart'
-    build_to: cache
-    builder_factories: ["SnippetsBuilder.new"]
-    build_extensions: {"": [".excerpt.json"]}
-    auto_apply: none
-
-targets:
-  prepare:
-    builders:
-      ":versions":
-        enabled: true
-      ":code_snippets":
-        enabled: true
-        generate_for:
-          - "lib/snippets/**/*.dart"
-          - "lib/snippets/*/*.drift"
-          - "lib/snippets/*.dart"
-    auto_apply_builders: false
-    sources:
-      - "$package$"
-      - "lib/versions.json"
-      - "lib/snippets/**"
-      - "tool/write_versions.dart"
-      - "tool/snippets.dart"
-
-  $default:
-    dependencies: [":prepare"]
-    builders:
-      build_web_compilers:entrypoint:
-        release_options:
-          # Turn of null assertions for release builds, it looks like this
-          # makes generated code slightly smaller.
-          native_null_assertions: false
-          dart2js_args:
-            - "-O4"
-            - "--csp"
-      moor_generator:
-        enabled: false
-    sources:
-      - "lib/**"
-      - "pages/**"
-      - "templates/**"
-      - "web/**"
-      - "$package$"
-      - "pubspec.yaml"
-      - "theme.yaml"
-      - "website.yaml"

docs/build.yaml

@@ -4,24 +4,54 @@ builders:
     build_to: cache
     builder_factories: ["writeVersions"]
     build_extensions: {"$package$": ["lib/versions.json"]}
+  api_index:
+    import: 'package:code_snippets/indexer.dart'
+    build_to: cache
+    builder_factories: ['DartIndexBuilder.new']
+    auto_apply: all_packages
+    runs_before: [code_snippets]
+    build_extensions: {"lib/lib": ['api.json']}
   code_snippets:
     import: 'tool/snippets.dart'
     build_to: cache
     builder_factories: ["SnippetsBuilder.new"]
     build_extensions: {"": [".excerpt.json"]}
     auto_apply: none
+    defaults:
+      options:
+        release: false
+      release_options:
+        release: true
 
 targets:
+  # We run drift and other builders first, syntax higlighting is more
+  # accurate if the generated classes exist.
+  source_gen:
+    auto_apply_builders: false
+    builders:
+      drift_dev:preparing_builder:
+        enabled: true
+      drift_dev:drift_dev:
+        enabled: true
+      json_serializable:
+        enabled: true
+    sources:
+     - lib/**
+
   prepare:
+    dependencies: [":source_gen"]
     builders:
       ":versions":
         enabled: true
       ":code_snippets":
         enabled: true
         generate_for:
-          - "lib/snippets/**/*.dart"
-          - "lib/snippets/*/*.drift"
-          - "lib/snippets/*.dart"
+          include:
+            - "lib/snippets/**/*.dart"
+            - "lib/snippets/*/*.drift"
+            - "lib/snippets/*.dart"
+          exclude:
+            - "**/*.g.dart"
     auto_apply_builders: false
     sources:
       - "$package$"
@@ -44,8 +74,17 @@ targets:
           dart2js_args:
             - "-O4"
             - "--csp"
+      # These builders should run in the source_gen target
+      drift_dev:preparing_builder:
+        enabled: false
+      drift_dev:drift_dev:
+        enabled: false
+      source_gen:combining_builder:
+        enabled: false
       moor_generator:
         enabled: false
+      json_serializable:
+        enabled: false
     sources:
       - "lib/**"
       - "pages/**"
@@ -55,3 +94,10 @@ targets:
       - "pubspec.yaml"
       - "theme.yaml"
       - "website.yaml"
+
+# Snippets referencing public API members from this package will get dartdoc links
+# embedded in them.
+global_options:
+  ":api_index":
+    options:
+      packages: ['drift', 'drift_dev']

docs/lib/_highlight.scss

@@ -1,9 +1,18 @@
+@use "sass:color";
+
+$background: #f8f8f8;
+
+.hljs a {
+  color: inherit;
+  text-decoration: underline dashed color.adjust($background, $lightness: -15%);
+  text-decoration-thickness: 1px;
+}
+
 .hljs {
   display: block;
   overflow-x: auto;
-  padding: 0.5em;
   color: #333;
-  background: #f8f8f8;
+  background: $background;
 }
 
 .hljs-comment,

docs/pubspec.yaml

@@ -6,6 +6,7 @@ environment:
   sdk: '>=2.15.0 <3.0.0'
 
 dependencies:
+  json_annotation: ^4.6.0
   docsy:
     hosted: https://simonbinder.eu
     version: ^0.2.2
@@ -18,13 +19,12 @@ dev_dependencies:
     hosted: https://simonbinder.eu
     version: ^0.2.9
   linkcheck: ^2.0.19
-  json_annotation: ^4.4.0
   json_serializable: ^6.1.6
   shelf: ^1.2.0
   shelf_static: ^1.1.0
   code_snippets:
     hosted: https://simonbinder.eu
-    version: ^0.0.6
+    version: ^0.0.7
 
   # Fake path_provider for snippets
   path_provider:

docs/templates/blocks/snippet.html

@@ -1,4 +1,4 @@
 {% assign excerpt = args.name | default: '(full)' %}
 <pre>
-<code>{{ args.snippets | get: excerpt }}</code>
+<code class="hljs">{{ args.snippets | get: excerpt }}</code>
 </pre>

docs/tool/ci_build.dart

@@ -41,12 +41,14 @@ Future<void> _waitForProcess(Process p, String name) async {
 }
 
 Future<void> _runBuildAndCopyFiles(Directory output, bool isRelease) async {
+  final siteEnv = isRelease ? 'prod' : 'preview';
+
   final buildArgs = [
     'run',
     'build_runner',
     'build',
     '--release',
-    if (isRelease) '--config=deploy',
+    '--define=built_site=environment=$siteEnv',
   ];
   final build = await Process.start('dart', buildArgs);
   await _waitForProcess(build, 'build');

docs/tool/snippets.dart

@@ -6,7 +6,15 @@ import 'package:sqlparser/sqlparser.dart';
 
 class SnippetsBuilder extends CodeExcerptBuilder {
   // ignore: avoid_unused_constructor_parameters
-  SnippetsBuilder([BuilderOptions? options]) : super(dropIndendation: true);
+  SnippetsBuilder([BuilderOptions? options])
+      : super(
+          dropIndendation: true,
+          overriddenDartDocUrls: {
+            // For CI builds, the dartdoc output for the drift package is added
+            // under the `api/` url.
+            if (options?.config['release'] == true) 'drift': Uri.parse('/api/'),
+          },
+        );
 
   @override
   bool shouldEmitFor(AssetId input, Excerpter excerpts) {