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

2022-09-21 11:33:08 -07:00
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>