Unverified Commit 1f0760a1 authored by Greg Spencer's avatar Greg Spencer Committed by GitHub

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

parent c546d159
**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 Flutter is Google's SDK for crafting beautiful, fast user experiences for
mobile, web, and desktop from a single codebase. Flutter works with existing mobile, web, and desktop from a single codebase. Flutter works with existing
...@@ -8,7 +8,7 @@ and open source. ...@@ -8,7 +8,7 @@ and open source.
This API reference covers all libraries that are exported by the Flutter This API reference covers all libraries that are exported by the Flutter
SDK. SDK.
### More Documentation ## More Documentation
This site hosts Flutter's API documentation. Other documentation can be found at This site hosts Flutter's API documentation. Other documentation can be found at
the following locations: the following locations:
...@@ -18,9 +18,9 @@ the following locations: ...@@ -18,9 +18,9 @@ the following locations:
* [Codelabs](https://flutter.dev/docs/codelabs) * [Codelabs](https://flutter.dev/docs/codelabs)
* [Contributing to Flutter](https://github.com/flutter/flutter/blob/master/CONTRIBUTING.md) * [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 Libraries in the "Libraries" section below (or in the left navigation) are part
of the core Flutter framework and are imported using of the core Flutter framework and are imported using
...@@ -31,7 +31,7 @@ import 'package:flutter/material.dart'; ...@@ -31,7 +31,7 @@ import 'package:flutter/material.dart';
import 'package:flutter/services.dart'; import 'package:flutter/services.dart';
``` ```
#### Dart Libraries ### Dart Libraries
Libraries in the "Dart" section exist in the `dart:` namespace and are imported Libraries in the "Dart" section exist in the `dart:` namespace and are imported
using `'dart:<library>'`, like so: using `'dart:<library>'`, like so:
...@@ -43,7 +43,7 @@ import 'dart:ui'; ...@@ -43,7 +43,7 @@ import 'dart:ui';
Except for `'dart:core'`, you must import a Dart library before you can use it. 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. Libraries in other sections are supporting libraries that ship with Flutter.
They are organized by package and are imported using They are organized by package and are imported using
...@@ -54,7 +54,7 @@ import 'package:flutter_test/flutter_test.dart'; ...@@ -54,7 +54,7 @@ import 'package:flutter_test/flutter_test.dart';
import 'package:file/local.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 has a rich ecosystem of packages that have been contributed by the
Flutter team and the broader open source community to a central repository. Flutter team and the broader open source community to a central repository.
......
/* Overrides for dartdoc styles. */ /* Overrides for dartdoc styles. */
body {
font-size: 15px;
font-family: Roboto, sans-serif;
line-height: 1.5;
color: #111;
background-color: #fdfdfd;
-webkit-font-smoothing: auto;
}
header { /* Prefer Open Sans for paragraph and other text */
background-color: white; body {
color: #424242; font-family: "Open Sans", "Roboto", sans-serif;
}
nav.navbar {
min-height: 57px;
padding: 6px 0;
} }
header.header-fixed nav.navbar-fixed-top { /* Prefer Google Sans for headers */
box-shadow: 0 1px 4px 0 rgba(0, 0, 0, 0.37); h1, h2, h3, h4, h5, h6 .h1, .h2, .h3, .h4, .h5, .h6 {
font-family: "Google Sans", "Roboto", sans-serif;
} }
h1 { .section-title, .breadcrumbs {
font-size: 42px !important; font-family: "Google Sans", "Roboto", sans-serif;
letter-spacing: -1px;
} }
/* Make all the h2 headings slightly bigger. */
h2 { h2 {
color: #111;
font-size: 24px;
}
.markdown h2 {
font-size: 24px; font-size: 24px;
} }
section.summary h2 { section.summary h2 {
font-size: 24px;
color: inherit; color: inherit;
border-bottom: none; border-bottom: none;
} }
.sidebar ol, pre {
.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;
margin: 0 0 15px 0; margin: 0 0 15px 0;
padding: 8px 12px; padding: 8px 12px;
border: 1px solid #cccccc;
border-radius: 4px; border-radius: 4px;
} }
code { code {
/* Inherit the background color, otherwise all inline code blocks have a
different color from the rest of the paragraph */
background-color: inherit; background-color: inherit;
font-size: 1em; /* browsers default to smaller font for code */ font-size: 1em; /* browsers default to smaller font for code */
padding-left: 0; /* otherwise we get ragged left margins */ padding-left: 0; /* otherwise we get ragged left margins */
padding-right: 0; padding-right: 0;
} }
/* Otherwise the description text is limited to a particular size instead of
filling up the center of the page. */
.markdown.desc { .markdown.desc {
max-width: inherit; max-width: inherit;
} }
/* Make the search box bigger and easier to read */
#search-box { #search-box {
color: #555; height: 24px;
background-color: #fff;
background-image: none;
border: 1px solid #ccc;
border-radius: 2px;
padding: 4px 6px;
font-size: 15px; font-size: 15px;
padding-left: 40px;
} }
/* Make the typeahead match the search box font size */
input.form-control.typeahead { input.form-control.typeahead {
padding: 4px 7px;
font-size: 15px; font-size: 15px;
} }
/* Make description list terms not be so dim. */
dl.dl-horizontal dt { dl.dl-horizontal dt {
color: inherit; 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 { 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 { code.hljs {
background: inherit; background: inherit;
} }
/* Make the footer smaller and less prominent. */
footer { footer {
font-size: 13px; font-size: 13px;
padding: 12px 20px; padding: 8px;
} }
/* Override the comment color for highlight.js to make it more /* Override the comment color for highlight.js to make it more
prominent/readable */ prominent. */
.hljs-comment { .hljs-comment {
color: #128c00; color: #128c00;
font-style: italic; font-style: italic;
font-weight: bold; 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 { img {
max-width: 100% 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);
}
/* Styles for handling custom code snippets */ /* Styles for handling custom code snippets */
.snippet-container { .snippet-container {
background-color: #2372a3;
padding: 10px; padding: 10px;
overflow: auto; overflow: auto;
} }
.snippet-description {
padding: 8px 40px 12px 8px;
}
.snippet-container pre { .snippet-container pre {
max-height: 500px; max-height: 500px;
overflow: auto; overflow: auto;
...@@ -25,28 +28,8 @@ ...@@ -25,28 +28,8 @@
position: relative; 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 { .snippet-buttons button {
background-color: #2372a3;
border-style: none; border-style: none;
color: white;
padding: 10px 24px; padding: 10px 24px;
cursor: pointer; cursor: pointer;
float: left; float: left;
...@@ -58,7 +41,9 @@ ...@@ -58,7 +41,9 @@
display: table; display: table;
} }
.snippet-buttons button:focus { outline: none; } .snippet-buttons button:focus {
outline: none;
}
.snippet-buttons button:hover { .snippet-buttons button:hover {
opacity: 1.0; opacity: 1.0;
...@@ -88,18 +73,19 @@ ...@@ -88,18 +73,19 @@
height: 500px; height: 500px;
} }
/* Styles for the deep-link anchor button */
.anchor-container { .anchor-container {
position: relative; position: relative;
} }
.anchor-button-overlay { .anchor-button-overlay {
position: absolute; position: absolute;
top: 0px; top: 5px;
right: 5px; right: 5px;
height: 28px; height: 28px;
width: 28px; width: 28px;
transition: .3s ease; transition: .3s ease;
background-color: #2372a3;
} }
.anchor-button { .anchor-button {
...@@ -108,7 +94,17 @@ ...@@ -108,7 +94,17 @@
cursor: pointer; cursor: pointer;
} }
.anchor-button :focus {
outline: 0px;
}
.anchor-button :hover {
transition: .3s ease;
opacity: 0.65;
}
/* Styles for the copy-to-clipboard button */ /* Styles for the copy-to-clipboard button */
.copyable-container { .copyable-container {
position: relative; position: relative;
} }
...@@ -120,7 +116,6 @@ ...@@ -120,7 +116,6 @@
height: 28px; height: 28px;
width: 28px; width: 28px;
transition: .3s ease; transition: .3s ease;
background-color: #2372a3;
} }
.copy-button { .copy-button {
...@@ -135,12 +130,36 @@ ...@@ -135,12 +130,36 @@
.copy-button :hover { .copy-button :hover {
transition: .3s ease; transition: .3s ease;
color: #222; opacity: 1.0;
} }
.copy-image { .copy-image {
opacity: 0.65; opacity: 0.65;
color: #2372a3;
font-size: 28px; font-size: 28px;
padding-top: 4px; 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
<!-- style overrides for dartdoc --> <!-- style overrides for dartdoc -->
<style> <style>
@import 'https://fonts.googleapis.com/css?family=Roboto:500,400italic,300,400,100i'; @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'; @import 'https://fonts.googleapis.com/css?family=Material+Icons|Material+Icons+Outlined|Material+Icons+Sharp|Material+Icons+Round';
</style> </style>
......
{@inject-html} {@inject-html}
<a name="{{id}}"></a> <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" <a class="anchor-button-overlay anchor-button" title="Copy link to clipboard"
onmouseenter="fixHref(this, '{{id}}');" onmouseenter="fixHref(this, '{{id}}');" onclick="fixHref(this, '{{id}}'); copyStringToClipboard(this.href);"
onclick="fixHref(this, '{{id}}'); copyStringToClipboard(this.href);"
href="#"> href="#">
<i class="material-icons copy-image">link</i> <i class="material-icons anchor-image">link</i>
</a> </a>
</div> <div class="snippet-description">
<div class="snippet-container"> <p>To create a local project with this code sample, run:<br />
<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/>
<span class="snippet-create-command">flutter create --sample={{id}} mysample</span> <span class="snippet-create-command">flutter create --sample={{id}} mysample</span>
</p>
</div> </div>
</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> </div>
{@end-inject-html} {@end-inject-html}
\ No newline at end of file
{@inject-html} {@inject-html}
<a name="{{id}}"></a> <a name="{{id}}"></a>
<div class="anchor-container"> <div class="snippet snippet-container 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>
</a>
</div>
<div class="snippet-container">
<div class="snippet">
{{description}} {{description}}
<div class="snippet-description">To create a local project with this code sample, run:<br/> <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 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> <span class="snippet-create-command">flutter create --sample={{id}} mysample</span>
</p>
</div> </div>
<div class="copyable-container"> <div class="copyable-container">
<button class="copy-button-overlay copy-button" title="Copy to clipboard" <button class="copy-button-overlay copy-button" title="Copy to clipboard"
onclick="copyTextToClipboard(longSnippet{{serial}});"> onclick="copyTextToClipboard(longSnippet{{serial}});">
<i class="material-icons copy-image">assignment</i> <i class="material-icons copy-image">assignment</i>
</button> </button>
<pre id="longSnippet{{serial}}" class="language-{{language}}"><code class="language-{{language}}">{{app}}</code></pre> <pre id="longSnippet{{serial}}"
</div> class="language-{{language}}"><code class="language-{{language}}">{{app}}</code></pre>
</div> </div>
</div> </div>
{@end-inject-html} {@end-inject-html}
\ No newline at end of file
{@inject-html} {@inject-html}
<a name="{{id}}"></a> <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" <a class="anchor-button-overlay anchor-button" title="Copy link to clipboard"
onmouseenter="fixHref(this, '{{id}}');" onmouseenter="fixHref(this, '{{id}}');" onclick="fixHref(this, '{{id}}'); copyStringToClipboard(this.href);"
onclick="fixHref(this, '{{id}}'); copyStringToClipboard(this.href);"
href="#"> href="#">
<i class="material-icons copy-image">link</i> <i class="material-icons anchor-image">link</i>
</a> </a>
</div>
<div class="snippet-container">
<div class="snippet">{{description}}
<div class="copyable-container"> <div class="copyable-container">
<button class="copy-button-overlay copy-button" title="Copy to clipboard" <button class="copy-button-overlay copy-button" title="Copy to clipboard"
onclick="copyTextToClipboard(findSiblingWithId(this, 'sample-code'));"> onclick="copyTextToClipboard(findSiblingWithId(this, 'sample-code'));">
...@@ -17,6 +14,5 @@ ...@@ -17,6 +14,5 @@
</button> </button>
<pre class="language-{{language}}" id="sample-code"><code class="language-{{language}}">{{code}}</code></pre> <pre class="language-{{language}}" id="sample-code"><code class="language-{{language}}">{{code}}</code></pre>
</div> </div>
</div>
</div> </div>
{@end-inject-html} {@end-inject-html}
\ No newline at end of file
...@@ -388,21 +388,17 @@ void cleanOutSnippets() { ...@@ -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()) { if (file.existsSync()) {
final List<String> contents = file.readAsLinesSync(); final RegExp regExp = RegExp(regExpString, dotAll: true);
bool found = false; final String contents = file.readAsStringSync();
for (final String line in contents) { if (!regExp.hasMatch(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."); throw Exception("Missing example code in ${file.path}. Either it didn't get published, publishing has changed, or the example no longer exists.");
} }
} else { } 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() { ...@@ -427,19 +423,22 @@ void sanityCheckDocs() {
// Make sure at least one example of each kind includes source code. // Make sure at least one example of each kind includes source code.
// Check a "sample" example, any one will do. // Check a "sample" example, any one will do.
final File sampleExample = File('$kPublishRoot/api/widgets/showGeneralDialog.html'); _sanityCheckExample(
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;;'); '$kPublishRoot/api/widgets/showGeneralDialog.html',
_sanityCheckExample(sampleExample, sampleRegExp); 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. // Check a "snippet" example, any one will do.
final File snippetExample = File('$kPublishRoot/api/widgets/ModalRoute/barrierColor.html'); _sanityCheckExample(
final RegExp snippetRegExp = RegExp(r'\s*<pre class="language-dart" id="sample-code">.*Color get barrierColor =&gt; Theme\.of\(navigator\.context\)\.colorScheme.background;.*</pre>'); '$kPublishRoot/api/widgets/ModalRoute/barrierColor.html',
_sanityCheckExample(snippetExample, snippetRegExp); r'\s*<pre.*id="sample-code">.*Color\s+get\s+barrierColor.*</pre>',
);
// Check a "dartpad" example, any one will do. // Check a "dartpad" example, any one will do.
final File dartpadExample = File('$kPublishRoot/api/widgets/PhysicalShape-class.html'); _sanityCheckExample(
final RegExp dartpadRegExp = RegExp(r'\s*<iframe class="snippet-dartpad" src="https://dartpad\.dev.*sample_id=widgets\.PhysicalShape\.\d+.*">\s*</iframe>'); '$kPublishRoot/api/widgets/PhysicalShape-class.html',
_sanityCheckExample(dartpadExample, dartpadRegExp); 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 /// Creates a custom index.html because we try to maintain old
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment