Fix API docs CSS files so dark mode works (#112023)
diff --git a/dev/docs/README.md b/dev/docs/README.md
index 669e978..c2d2679 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 @@
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 @@
* [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/services.dart';
```
-#### Dart Libraries
+### Dart Libraries
Libraries in the "Dart" section exist in the `dart:` namespace and are imported
using `'dart:<library>'`, like so:
@@ -43,7 +43,7 @@
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: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 ee3d3f9..409ec99 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;
+.section-title, .breadcrumbs {
+ font-family: "Google Sans", "Roboto", sans-serif;
}
-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;
-}
-
+/* 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 02f2b13..048edf5 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 554a797..dd2404c 100644
--- a/dev/docs/styles.html
+++ b/dev/docs/styles.html
@@ -1,6 +1,8 @@
<!-- style overrides for dartdoc -->
<style>
@import 'https://fonts.googleapis.com/css?family=Roboto:500,400italic,300,400,100i';
+@import 'https://fonts.googleapis.com/css?family=Google+Sans:500,400italic,300,400,100i';
+@import 'https://fonts.googleapis.com/css?family=Open+Sans:500,400italic,300,400,100i';
@import 'https://fonts.googleapis.com/css?family=Material+Icons|Material+Icons+Outlined|Material+Icons+Sharp|Material+Icons+Round';
</style>
diff --git a/dev/snippets/config/skeletons/dartpad-sample.html b/dev/snippets/config/skeletons/dartpad-sample.html
index c381b34..48b726b 100644
--- a/dev/snippets/config/skeletons/dartpad-sample.html
+++ b/dev/snippets/config/skeletons/dartpad-sample.html
@@ -1,20 +1,19 @@
{@inject-html}
<a name="{{id}}"></a>
-<div class="anchor-container">
+<div class="snippet snippet-container anchor-container" id="longSnippet{{serial}}">
+ {{description}}
<a class="anchor-button-overlay anchor-button" title="Copy link to clipboard"
- onmouseenter="fixHref(this, '{{id}}');"
- onclick="fixHref(this, '{{id}}'); copyStringToClipboard(this.href);"
- href="#">
- <i class="material-icons copy-image">link</i>
+ onmouseenter="fixHref(this, '{{id}}');" onclick="fixHref(this, '{{id}}'); copyStringToClipboard(this.href);"
+ href="#">
+ <i class="material-icons anchor-image">link</i>
</a>
-</div>
-<div class="snippet-container">
- <div class="snippet" id="longSnippet{{serial}}">
- {{description}}
- <iframe class="snippet-dartpad" src="https://dartpad.dev/embed-flutter.html?split=60&run=true&null_safety=true&sample_id={{id}}&sample_channel={{channel}}"></iframe>
- <div class="snippet-description">To create a local project with this code sample, run:<br/>
+ <div class="snippet-description">
+ <p>To create a local project with this code sample, run:<br />
<span class="snippet-create-command">flutter create --sample={{id}} mysample</span>
- </div>
+ </p>
</div>
+ <iframe class="snippet-dartpad"
+ src="https://dartpad.dev/embed-flutter.html?split=60&run=true&null_safety=true&sample_id={{id}}&sample_channel={{channel}}">
+ </iframe>
</div>
-{@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 e4b672f..a2816b0 100644
--- a/dev/snippets/config/skeletons/sample.html
+++ b/dev/snippets/config/skeletons/sample.html
@@ -1,26 +1,23 @@
{@inject-html}
<a name="{{id}}"></a>
-<div class="anchor-container">
- <a class="anchor-button-overlay anchor-button" title="Copy link to clipboard"
- onmouseenter="fixHref(this, '{{id}}');"
- onclick="fixHref(this, '{{id}}'); copyStringToClipboard(this.href);"
- href="#">
- <i class="material-icons copy-image">link</i>
+<div class="snippet snippet-container anchor-container">
+ {{description}}
+ <a class="anchor-button-overlay anchor-button" title="Copy link to clipboard" onmouseenter="fixHref(this, '{{id}}');"
+ onclick="fixHref(this, '{{id}}'); copyStringToClipboard(this.href);" href="#">
+ <i class="material-icons anchor-image">link</i>
</a>
-</div>
-<div class="snippet-container">
- <div class="snippet">
- {{description}}
- <div class="snippet-description">To create a local project with this code sample, run:<br/>
+ <div class="snippet-description">
+ <p>To create a local project with this code sample, run:<br />
<span class="snippet-create-command">flutter create --sample={{id}} mysample</span>
- </div>
- <div class="copyable-container">
- <button class="copy-button-overlay copy-button" title="Copy to clipboard"
- onclick="copyTextToClipboard(longSnippet{{serial}});">
- <i class="material-icons copy-image">assignment</i>
- </button>
- <pre id="longSnippet{{serial}}" class="language-{{language}}"><code class="language-{{language}}">{{app}}</code></pre>
- </div>
+ </p>
+ </div>
+ <div class="copyable-container">
+ <button class="copy-button-overlay copy-button" title="Copy to clipboard"
+ onclick="copyTextToClipboard(longSnippet{{serial}});">
+ <i class="material-icons copy-image">assignment</i>
+ </button>
+ <pre id="longSnippet{{serial}}"
+ class="language-{{language}}"><code class="language-{{language}}">{{app}}</code></pre>
</div>
</div>
-{@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 99574b0..b9ca0b7 100644
--- a/dev/snippets/config/skeletons/snippet.html
+++ b/dev/snippets/config/skeletons/snippet.html
@@ -1,22 +1,18 @@
{@inject-html}
<a name="{{id}}"></a>
-<div class="anchor-container">
+<div class="snippet snippet-container anchor-container">
+ {{description}}
<a class="anchor-button-overlay anchor-button" title="Copy link to clipboard"
- onmouseenter="fixHref(this, '{{id}}');"
- onclick="fixHref(this, '{{id}}'); copyStringToClipboard(this.href);"
- href="#">
- <i class="material-icons copy-image">link</i>
+ onmouseenter="fixHref(this, '{{id}}');" onclick="fixHref(this, '{{id}}'); copyStringToClipboard(this.href);"
+ href="#">
+ <i class="material-icons anchor-image">link</i>
</a>
-</div>
-<div class="snippet-container">
- <div class="snippet">{{description}}
- <div class="copyable-container">
- <button class="copy-button-overlay copy-button" title="Copy to clipboard"
- onclick="copyTextToClipboard(findSiblingWithId(this, 'sample-code'));">
- <i class="material-icons copy-image">assignment</i>
- </button>
- <pre class="language-{{language}}" id="sample-code"><code class="language-{{language}}">{{code}}</code></pre>
- </div>
+ <div class="copyable-container">
+ <button class="copy-button-overlay copy-button" title="Copy to clipboard"
+ onclick="copyTextToClipboard(findSiblingWithId(this, 'sample-code'));">
+ <i class="material-icons copy-image">assignment</i>
+ </button>
+ <pre class="language-{{language}}" id="sample-code"><code class="language-{{language}}">{{code}}</code></pre>
</div>
</div>
-{@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 0fde6bf..f7f94c8 100644
--- a/dev/tools/dartdoc.dart
+++ b/dev/tools/dartdoc.dart
@@ -388,21 +388,17 @@
}
}
-void _sanityCheckExample(File file, RegExp regExp) {
+void _sanityCheckExample(String fileString, String regExpString) {
+ final File file = File(fileString);
if (file.existsSync()) {
- final List<String> 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 @@
// 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*<pre id="longSnippet1" class="language-dart">\s*<code class="language-dart">\s*import 'package:flutter/material.dart';');
- _sanityCheckExample(sampleExample, sampleRegExp);
+ _sanityCheckExample(
+ '$kPublishRoot/api/widgets/showGeneralDialog.html',
+ r'\s*<pre\s+id="longSnippet1".*<code\s+class="language-dart">\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*<pre class="language-dart" id="sample-code">.*Color get barrierColor => Theme\.of\(navigator\.context\)\.colorScheme.background;.*</pre>');
- _sanityCheckExample(snippetExample, snippetRegExp);
+ _sanityCheckExample(
+ '$kPublishRoot/api/widgets/ModalRoute/barrierColor.html',
+ r'\s*<pre.*id="sample-code">.*Color\s+get\s+barrierColor.*</pre>',
+ );
// Check a "dartpad" example, any one will do.
- final File dartpadExample = File('$kPublishRoot/api/widgets/PhysicalShape-class.html');
- final RegExp dartpadRegExp = RegExp(r'\s*<iframe class="snippet-dartpad" src="https://dartpad\.dev.*sample_id=widgets\.PhysicalShape\.\d+.*">\s*</iframe>');
- _sanityCheckExample(dartpadExample, dartpadRegExp);
+ _sanityCheckExample(
+ '$kPublishRoot/api/widgets/PhysicalShape-class.html',
+ r'\s*<iframe\s+class="snippet-dartpad"\s+src="https://dartpad\.dev.*sample_id=widgets\.PhysicalShape\.\d+.*">\s*</iframe>',
+ );
}
/// Creates a custom index.html because we try to maintain old
