diff --git a/dev/docs/README.md b/dev/docs/README.md index 669e978722b..c2d2679447b 100644 --- a/dev/docs/README.md +++ b/dev/docs/README.md @@ -1,4 +1,4 @@ -**Welcome to the Flutter API reference documentation!** +# Welcome to the Flutter API reference documentation! Flutter is Google's SDK for crafting beautiful, fast user experiences for mobile, web, and desktop from a single codebase. Flutter works with existing @@ -8,7 +8,7 @@ and open source. This API reference covers all libraries that are exported by the Flutter SDK. -### More Documentation +## More Documentation This site hosts Flutter's API documentation. Other documentation can be found at the following locations: @@ -18,9 +18,9 @@ the following locations: * [Codelabs](https://flutter.dev/docs/codelabs) * [Contributing to Flutter](https://github.com/flutter/flutter/blob/master/CONTRIBUTING.md) -### Importing a Library +## Importing a Library -#### Framework Libraries +### Framework Libraries Libraries in the "Libraries" section below (or in the left navigation) are part of the core Flutter framework and are imported using @@ -31,7 +31,7 @@ import 'package:flutter/material.dart'; import 'package:flutter/services.dart'; ``` -#### Dart Libraries +### Dart Libraries Libraries in the "Dart" section exist in the `dart:` namespace and are imported using `'dart:'`, like so: @@ -43,7 +43,7 @@ import 'dart:ui'; Except for `'dart:core'`, you must import a Dart library before you can use it. -#### Supporting Libraries +### Supporting Libraries Libraries in other sections are supporting libraries that ship with Flutter. They are organized by package and are imported using @@ -54,7 +54,7 @@ import 'package:flutter_test/flutter_test.dart'; import 'package:file/local.dart'; ``` -### Packages on pub.dev +## Packages on pub.dev Flutter has a rich ecosystem of packages that have been contributed by the Flutter team and the broader open source community to a central repository. diff --git a/dev/docs/assets/overrides.css b/dev/docs/assets/overrides.css index ee3d3f9931a..409ec9972a0 100644 --- a/dev/docs/assets/overrides.css +++ b/dev/docs/assets/overrides.css @@ -1,134 +1,162 @@ /* Overrides for dartdoc styles. */ + +/* Prefer Open Sans for paragraph and other text */ body { - font-size: 15px; - font-family: Roboto, sans-serif; - line-height: 1.5; - color: #111; - background-color: #fdfdfd; - -webkit-font-smoothing: auto; + font-family: "Open Sans", "Roboto", sans-serif; } -header { - background-color: white; - color: #424242; +/* Prefer Google Sans for headers */ +h1, h2, h3, h4, h5, h6 .h1, .h2, .h3, .h4, .h5, .h6 { + font-family: "Google Sans", "Roboto", sans-serif; } -nav.navbar { - min-height: 57px; - padding: 6px 0; -} - -header.header-fixed nav.navbar-fixed-top { - box-shadow: 0 1px 4px 0 rgba(0, 0, 0, 0.37); -} - -h1 { - font-size: 42px !important; - letter-spacing: -1px; +.section-title, .breadcrumbs { + font-family: "Google Sans", "Roboto", sans-serif; } +/* Make all the h2 headings slightly bigger. */ h2 { - color: #111; - font-size: 24px; -} - -.markdown h2 { font-size: 24px; } section.summary h2 { - font-size: 24px; color: inherit; border-bottom: none; } -.sidebar ol, -.sidebar ol li.section-title { - font-size: inherit; -} - -@media screen and (max-width: 768px) { - .sidebar-offcanvas-left.active { - padding: 10px; - } -} - -.sidebar-offcanvas-left ol { - padding: 0 16px 16px 0; -} - -.sidebar-offcanvas-left h5 { - display: none; -} - -pre, -pre.prettyprint, -pre > code { - font-size: 14px; -} - -pre, -pre.prettyprint { - background: #f5f2f0; +pre { margin: 0 0 15px 0; padding: 8px 12px; - border: 1px solid #cccccc; border-radius: 4px; } code { + /* Inherit the background color, otherwise all inline code blocks have a + different color from the rest of the paragraph */ background-color: inherit; font-size: 1em; /* browsers default to smaller font for code */ padding-left: 0; /* otherwise we get ragged left margins */ padding-right: 0; } +/* Otherwise the description text is limited to a particular size instead of + filling up the center of the page. */ .markdown.desc { max-width: inherit; } +/* Make the search box bigger and easier to read */ #search-box { - color: #555; - background-color: #fff; - background-image: none; - border: 1px solid #ccc; - border-radius: 2px; - padding: 4px 6px; + height: 24px; font-size: 15px; + padding-left: 40px; } +/* Make the typeahead match the search box font size */ input.form-control.typeahead { - padding: 4px 7px; font-size: 15px; } +/* Make description list terms not be so dim. */ dl.dl-horizontal dt { color: inherit; } -/* Line the material icons up with their labels */ +/* Line the material icons up with their labels + See https://api.flutter.dev/flutter/material/Icons-class.html + for where this matters. + */ i.md-36 { - vertical-align: bottom; + vertical-align: middle; } -/* address a style issue with the background of code sections */ +/* Address a style issue with the background of code sections. Without this, the + code inside a code block has a different background from the rest of the box. */ code.hljs { background: inherit; } +/* Make the footer smaller and less prominent. */ footer { font-size: 13px; - padding: 12px 20px; + padding: 8px; } + /* Override the comment color for highlight.js to make it more - prominent/readable */ + prominent. */ .hljs-comment { color: #128c00; font-style: italic; font-weight: bold; } -/* Constrain image width to container */ +/* Make the summary headers contrast a bit with text. */ +.summary h2 { + opacity: 0.8; +} + +/* Constrain the image width to the container so that images resize instead of + causing the page to scroll horizontally */ img { max-width: 100% } + +/* Light/Dark Theme adjustments */ + +.light-theme { + /* This is the same link color as the main Flutter site */ + --main-hyperlinks-color: rgb(19, 137, 253); + --main-footer-background: #eee; +} + +.dark-theme { + --main-hyperlinks-color: rgb(81, 167, 254); +} + +.light-theme footer { + color: rgb(74, 74, 74); +} + +.dark-theme footer { + color:rgb(220, 220, 220); +} + +body.light-theme { + color:rgb(74, 74, 74); +} + +body.dark-theme { + color:rgb(220, 220, 220); +} + +.dark-theme .multi-line-signature .name { + color: rgb(163, 163, 163); +} + +.dark-theme .parameter-name { + color: rgb(163, 163, 163); +} + +.dark-theme .parameter { + color: rgb(163, 163, 163); +} + +.light-theme pre { + border: 1px solid white; + color: #222; + background-color:#eee; +} + +.dark-theme pre { + border: 1px solid #444; + color: white; + background-color:rgb(23, 32, 43); +} + +.dark-theme .hljs-string { + color:rgb(255, 100, 100); +} + +.dark-theme .hljs-title { + color:rgb(192, 184, 255); +} diff --git a/dev/docs/assets/snippets.css b/dev/docs/assets/snippets.css index 02f2b1360ac..048edf5a487 100644 --- a/dev/docs/assets/snippets.css +++ b/dev/docs/assets/snippets.css @@ -1,10 +1,13 @@ /* Styles for handling custom code snippets */ .snippet-container { - background-color: #2372a3; padding: 10px; overflow: auto; } +.snippet-description { + padding: 8px 40px 12px 8px; +} + .snippet-container pre { max-height: 500px; overflow: auto; @@ -25,28 +28,8 @@ position: relative; } -.snippet-description { - padding: 10px; - color: white; -} - -.snippet-description a:link { - color: #c7fcf4; -} -.snippet-description a:visited { - color: #c7dbfc; -} -.snippet-description a:hover { - color: white; -} -.snippet-description a:active { - color: #80b0fc; -} - .snippet-buttons button { - background-color: #2372a3; border-style: none; - color: white; padding: 10px 24px; cursor: pointer; float: left; @@ -58,7 +41,9 @@ display: table; } -.snippet-buttons button:focus { outline: none; } +.snippet-buttons button:focus { + outline: none; +} .snippet-buttons button:hover { opacity: 1.0; @@ -88,18 +73,19 @@ height: 500px; } +/* Styles for the deep-link anchor button */ + .anchor-container { position: relative; } .anchor-button-overlay { position: absolute; - top: 0px; + top: 5px; right: 5px; height: 28px; width: 28px; transition: .3s ease; - background-color: #2372a3; } .anchor-button { @@ -108,7 +94,17 @@ cursor: pointer; } +.anchor-button :focus { + outline: 0px; +} + +.anchor-button :hover { + transition: .3s ease; + opacity: 0.65; +} + /* Styles for the copy-to-clipboard button */ + .copyable-container { position: relative; } @@ -120,7 +116,6 @@ height: 28px; width: 28px; transition: .3s ease; - background-color: #2372a3; } .copy-button { @@ -135,12 +130,36 @@ .copy-button :hover { transition: .3s ease; - color: #222; + opacity: 1.0; } .copy-image { opacity: 0.65; - color: #2372a3; font-size: 28px; padding-top: 4px; + color: var(--main-hyperlinks-color); } + +/* Light/Dark theme modifications */ + +.dark-theme .snippet-buttons button { + background-color: #133e59; + color: rgb(149, 149, 149); +} + +.light-theme .snippet-buttons button { + background-color: #2372a3; + color: white; +} + +.light-theme .snippet-container { + --main-hyperlinks-color: #005cc6; +} + +.dark-theme .snippet-container { + background-color: rgb(30, 40, 51); +} + +.light-theme .snippet-container { + background-color: rgb(215, 235, 252); +} \ No newline at end of file diff --git a/dev/docs/styles.html b/dev/docs/styles.html index 554a797c35b..dd2404c5a47 100644 --- a/dev/docs/styles.html +++ b/dev/docs/styles.html @@ -1,6 +1,8 @@ diff --git a/dev/snippets/config/skeletons/dartpad-sample.html b/dev/snippets/config/skeletons/dartpad-sample.html index c381b3476c4..48b726b30b3 100644 --- a/dev/snippets/config/skeletons/dartpad-sample.html +++ b/dev/snippets/config/skeletons/dartpad-sample.html @@ -1,20 +1,19 @@ {@inject-html} -
+ -
-
- {{description}} - -
To create a local project with this code sample, run:
+
+

To create a local project with this code sample, run:
flutter create --sample={{id}} mysample -

+

+
-{@end-inject-html} +{@end-inject-html} \ No newline at end of file diff --git a/dev/snippets/config/skeletons/sample.html b/dev/snippets/config/skeletons/sample.html index e4b672fa694..a2816b004b3 100644 --- a/dev/snippets/config/skeletons/sample.html +++ b/dev/snippets/config/skeletons/sample.html @@ -1,26 +1,23 @@ {@inject-html} -
- - link +
+ {{description}} + + link -
-
-
- {{description}} -
To create a local project with this code sample, run:
+
+

To create a local project with this code sample, run:
flutter create --sample={{id}} mysample -

-
- - 
{{app}}
-
+

+
+
+ + 
{{app}}
-{@end-inject-html} +{@end-inject-html} \ No newline at end of file diff --git a/dev/snippets/config/skeletons/snippet.html b/dev/snippets/config/skeletons/snippet.html index 99574b028b8..b9ca0b727cb 100644 --- a/dev/snippets/config/skeletons/snippet.html +++ b/dev/snippets/config/skeletons/snippet.html @@ -1,22 +1,18 @@ {@inject-html} -
+
+ {{description}} - link + onmouseenter="fixHref(this, '{{id}}');" onclick="fixHref(this, '{{id}}'); copyStringToClipboard(this.href);" + href="#"> + link -
-
-
{{description}} -
- - 
{{code}}
-
+
+ + 
{{code}}
-{@end-inject-html} +{@end-inject-html} \ No newline at end of file diff --git a/dev/tools/dartdoc.dart b/dev/tools/dartdoc.dart index 0fde6bf4b45..f7f94c83746 100644 --- a/dev/tools/dartdoc.dart +++ b/dev/tools/dartdoc.dart @@ -388,21 +388,17 @@ void cleanOutSnippets() { } } -void _sanityCheckExample(File file, RegExp regExp) { +void _sanityCheckExample(String fileString, String regExpString) { + final File file = File(fileString); 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) { + final RegExp regExp = RegExp(regExpString, dotAll: true); + final String contents = file.readAsStringSync(); + if (!regExp.hasMatch(contents)) { 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."); + 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."); } } @@ -427,19 +423,22 @@ void sanityCheckDocs() { // 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);
+  _sanityCheckExample(
+    '$kPublishRoot/api/widgets/showGeneralDialog.html',
+    r'\s*\s*import 'package:flutter/material.dart';',
+  );
 
   // 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\)\.colorScheme.background;.*
');
-  _sanityCheckExample(snippetExample, snippetRegExp);
+  _sanityCheckExample(
+    '$kPublishRoot/api/widgets/ModalRoute/barrierColor.html',
+    r'\s*.*Color\s+get\s+barrierColor.*
', + ); // 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); + _sanityCheckExample( + '$kPublishRoot/api/widgets/PhysicalShape-class.html', + r'\s*\s*', + ); } /// Creates a custom index.html because we try to maintain old