From 5332b8680b598a9f84d7e5764f4b52a19fef3e94 Mon Sep 17 00:00:00 2001 From: Simon Binder Date: Sun, 10 Jul 2022 14:27:56 +0200 Subject: [PATCH] Doc snippets: Link to relevant dartdoc page --- docs/build.deploy.yaml | 54 ------------------------------ docs/build.yaml | 52 ++++++++++++++++++++++++++-- docs/lib/_highlight.scss | 13 +++++-- docs/pubspec.yaml | 4 +-- docs/templates/blocks/snippet.html | 2 +- docs/tool/ci_build.dart | 4 ++- docs/tool/snippets.dart | 10 +++++- 7 files changed, 75 insertions(+), 64 deletions(-) delete mode 100644 docs/build.deploy.yaml diff --git a/docs/build.deploy.yaml b/docs/build.deploy.yaml deleted file mode 100644 index 02972ed1..00000000 --- a/docs/build.deploy.yaml +++ /dev/null @@ -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" diff --git a/docs/build.yaml b/docs/build.yaml index 9d753787..416fe544 100644 --- a/docs/build.yaml +++ b/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'] diff --git a/docs/lib/_highlight.scss b/docs/lib/_highlight.scss index 878e7f7f..80f489ba 100644 --- a/docs/lib/_highlight.scss +++ b/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, diff --git a/docs/pubspec.yaml b/docs/pubspec.yaml index d83acb43..a21b522f 100644 --- a/docs/pubspec.yaml +++ b/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: diff --git a/docs/templates/blocks/snippet.html b/docs/templates/blocks/snippet.html index a8f4bcf5..b1fbf0e5 100644 --- a/docs/templates/blocks/snippet.html +++ b/docs/templates/blocks/snippet.html @@ -1,4 +1,4 @@ {% assign excerpt = args.name | default: '(full)' %} 
-{{ args.snippets | get: excerpt }}
+{{ args.snippets | get: excerpt }}
diff --git a/docs/tool/ci_build.dart b/docs/tool/ci_build.dart index 14ec1003..638579c6 100644 --- a/docs/tool/ci_build.dart +++ b/docs/tool/ci_build.dart @@ -41,12 +41,14 @@ Future _waitForProcess(Process p, String name) async { } Future _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'); diff --git a/docs/tool/snippets.dart b/docs/tool/snippets.dart index 975dce8e..3254b8c5 100644 --- a/docs/tool/snippets.dart +++ b/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) {