Fix API docs CSS files so dark mode works (#112023)

2024-08-25 11:07:06 +00:00 · 2022-09-21 11:33:08 -07:00 · 2022-09-21 11:33:08 -07:00 · 1f0760a1cc
parent c546d15965
commit 1f0760a1cc
8 changed files with 212 additions and 172 deletions
--- 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:<library>'`, 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.
--- 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);
+}
--- 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);
+}
--- 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>

--- 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&amp;run=true&amp;null_safety=true&amp;sample_id={{id}}&amp;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&amp;run=true&amp;null_safety=true&amp;sample_id={{id}}&amp;sample_channel={{channel}}">
+    </iframe>
 </div>
-{@end-inject-html}
+{@end-inject-html}
--- 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}
--- 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}
--- 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<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 @@ 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*<pre id="longSnippet1" class="language-dart">\s*<code class="language-dart">\s*import &#39;package:flutter&#47;material.dart&#39;;');
-  _sanityCheckExample(sampleExample, sampleRegExp);
+  _sanityCheckExample(
+    '$kPublishRoot/api/widgets/showGeneralDialog.html',
+    r'\s*<pre\s+id="longSnippet1".*<code\s+class="language-dart">\s*import &#39;package:flutter&#47;material.dart&#39;;',
+  );

  // 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 =&gt; 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