diff --git a/dev/bots/docs.sh b/dev/bots/docs.sh index 2d154430ec2..4463b9f0cde 100755 --- a/dev/bots/docs.sh +++ b/dev/bots/docs.sh @@ -28,11 +28,6 @@ function generate_docs() { # >>> If you update this version, also update it in dev/bots/analyze_sample_code.dart <<< "$DART" pub global activate snippets 0.2.5 - # Run the snippets tool once to force building of the package executable, - # since "dart pub global run" has issues with startup concurrency. - # TODO(gspencergoog): Remove once pub issue is fixed, https://github.com/dart-lang/pub/issues/3165 - "$DART" pub global run snippets --help - # This script generates a unified doc set, and creates # a custom index.html, placing everything into dev/docs/doc. (cd "$FLUTTER_ROOT/dev/tools" && "$FLUTTER" pub get) diff --git a/dev/snippets/config/skeletons/sample.html b/dev/snippets/config/skeletons/sample.html index 92dd25aa832..e4b672fa694 100644 --- a/dev/snippets/config/skeletons/sample.html +++ b/dev/snippets/config/skeletons/sample.html @@ -8,35 +8,18 @@ link -
- - - -
-
+
{{description}} -
- -
{{code}}
-
-
-
diff --git a/dev/tools/dartdoc.dart b/dev/tools/dartdoc.dart index 620168fb00e..6a0b128e16b 100644 --- a/dev/tools/dartdoc.dart +++ b/dev/tools/dartdoc.dart @@ -381,6 +381,25 @@ void cleanOutSnippets() { } } +void _sanityCheckExample(File file, RegExp regExp) { + if (file.existsSync()) { + final List contents = file.readAsLinesSync(); + bool found = false; + for (final String line in contents) { + if (regExp.matchAsPrefix(line) != null) { + found = true; + break; + } + } + if (!found) { + throw Exception("Missing example code in ${file.path}. Either it didn't get published, publishing has changed, or the example no longer exists."); + } + } else { + throw Exception("Missing example code sanity test file ${file.path}. Either it didn't get published, or you might have to update the test to look at a different file."); + } +} + +/// Runs a sanity check by running a test. void sanityCheckDocs() { final List canaries = [ '$kPublishRoot/assets/overrides.css', @@ -397,6 +416,22 @@ void sanityCheckDocs() { if (!File(canary).existsSync()) throw Exception('Missing "$canary", which probably means the documentation failed to build correctly.'); } + // Make sure at least one example of each kind includes source code. + + // Check a "sample" example, any one will do. + final File sampleExample = File('$kPublishRoot/api/widgets/showGeneralDialog.html'); + final RegExp sampleRegExp = RegExp(r'\s*
\s*\s*import 'package:flutter/material.dart';');
+  _sanityCheckExample(sampleExample, sampleRegExp);
+
+  // Check a "snippet" example, any one will do.
+  final File snippetExample = File('$kPublishRoot/api/widgets/ModalRoute/barrierColor.html');
+  final RegExp snippetRegExp = RegExp(r'\s*
.*Color get barrierColor => Theme\.of\(navigator\.context\)\.backgroundColor;.*
'); + _sanityCheckExample(snippetExample, snippetRegExp); + + // Check a "dartpad" example, any one will do. + final File dartpadExample = File('$kPublishRoot/api/widgets/PhysicalShape-class.html'); + final RegExp dartpadRegExp = RegExp(r'\s*'); + _sanityCheckExample(dartpadExample, dartpadRegExp); } /// Creates a custom index.html because we try to maintain old