Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add fallback text for sidebar failing to load #3643

Merged
merged 3 commits into from
Feb 20, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
## 8.0.6-wip

* Add troubleshooting information when the sidebars failed to load.

## 8.0.5

* Require `analyzer: ^6.4.1`.
Expand Down
2 changes: 1 addition & 1 deletion dartdoc_options.yaml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
dartdoc:
linkToSource:
root: '.'
uriTemplate: 'https://github.com/dart-lang/dartdoc/blob/v8.0.5/%f%#L%l%'
uriTemplate: 'https://github.com/dart-lang/dartdoc/blob/v8.0.6-wip/%f%#L%l%'
6,335 changes: 3,154 additions & 3,181 deletions lib/resources/docs.dart.js

Large diffs are not rendered by default.

12 changes: 6 additions & 6 deletions lib/resources/docs.dart.js.map

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion lib/src/version.dart
Original file line number Diff line number Diff line change
@@ -1 +1 @@
const packageVersion = '8.0.5';
const packageVersion = '8.0.6-wip';
3 changes: 1 addition & 2 deletions pubspec.yaml
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
name: dartdoc
version: 8.0.5
version: 8.0.6-wip
description: A non-interactive HTML documentation generator for Dart source code.
repository: https://github.com/dart-lang/dartdoc

Expand All @@ -25,7 +25,6 @@ dependencies:
dev_dependencies:
async: ^2.11.0
dart_style: ^2.3.4
js: ^0.7.0
lints: ^3.0.0
matcher: ^0.12.15
test: ^1.24.2
Expand Down
62 changes: 39 additions & 23 deletions web/docs.dart
Original file line number Diff line number Diff line change
Expand Up @@ -8,56 +8,72 @@ import 'highlight.dart' as highlight;
import 'search.dart' as search;
import 'sidenav.dart' as sidenav;
import 'theme.dart' as theme;
import 'web_interop.dart';

void main() {
highlight.init();
initializeSidebars();
sidenav.init();
search.init();
sidenav.init();
highlight.init();
theme.init();
}

void initializeSidebars() {
final body = document.querySelector('body');
final body = document.body;
if (body == null) {
return;
}
final dataUsingBaseHref = body.dataset['using-base-href'];
final dataUsingBaseHref = body.getAttribute('data-using-base-href');
if (dataUsingBaseHref == null) {
// This should never happen.
return;
}
var baseHref = '';
final String baseHref;
if (dataUsingBaseHref != 'true') {
final dataBaseHref = body.dataset['base-href'];
final dataBaseHref = body.getAttribute('data-base-href');
if (dataBaseHref == null) {
return;
}
baseHref = dataBaseHref;
} else {
baseHref = '';
}
final mainContent = document.querySelector('#dartdoc-main-content');

final mainContent = document.getElementById('dartdoc-main-content');
if (mainContent == null) {
return;
}
final aboveSidebarPath = mainContent.dataset['above-sidebar'];
final leftSidebar = document.querySelector('#dartdoc-sidebar-left-content');
final sanitizer = _SidebarNodeTreeSanitizer(baseHref);
if (aboveSidebarPath != null &&
aboveSidebarPath.isNotEmpty &&
leftSidebar != null) {
HttpRequest.getString('$baseHref$aboveSidebarPath').then((content) {
leftSidebar.setInnerHtml(content, treeSanitizer: sanitizer);
});
}
final belowSidebarPath = mainContent.dataset['below-sidebar'];
final rightSidebar = document.querySelector('#dartdoc-sidebar-right');
if (belowSidebarPath != null &&
belowSidebarPath.isNotEmpty &&
rightSidebar != null) {
HttpRequest.getString('$baseHref$belowSidebarPath').then((content) {
rightSidebar.setInnerHtml(content, treeSanitizer: sanitizer);

void loadSidebar(String? sidebarPath, Element? sidebarElement) {
if (sidebarPath == null || sidebarPath.isEmpty || sidebarElement == null) {
return;
}

window.fetch('$baseHref$sidebarPath').then((response) async {
final fetchResponse = response as FetchResponse;
if (response.status != 200) {
final errorAnchor = (document.createElement('a') as AnchorElement)
..href = 'https://dart.dev/tools/dart-doc#troubleshoot'
..text = 'Failed to load sidebar. '
'Visit dart.dev for help troubleshooting.';
sidebarElement.append(errorAnchor);
return;
}

final content = await fetchResponse.text;

sidebarElement.setInnerHtml(content, treeSanitizer: sanitizer);
});
}

final aboveSidebarPath = mainContent.getAttribute('data-above-sidebar');
final leftSidebar = document.getElementById('dartdoc-sidebar-left-content');
loadSidebar(aboveSidebarPath, leftSidebar);

final belowSidebarPath = mainContent.getAttribute('data-below-sidebar');
final rightSidebar = document.getElementById('dartdoc-sidebar-right');
loadSidebar(belowSidebarPath, rightSidebar);
}

/// A permissive sanitizer that allows external links (e.g. to api.dart.dev) and
Expand Down
4 changes: 2 additions & 2 deletions web/highlight.dart
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,15 @@
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

import 'package:js/js.dart';
import 'dart:js_interop';

void init() {
highlight?.highlightAll();
}

@JS()
@staticInterop
class HighlightJs {}
final class HighlightJs {}

extension HighlightJsExtension on HighlightJs {
external void highlightAll();
Expand Down
7 changes: 3 additions & 4 deletions web/search.dart
Original file line number Diff line number Diff line change
Expand Up @@ -36,14 +36,13 @@ void init() {
}

window.fetch('${_htmlBase}index.json').then((response) async {
response = response as FetchResponse;
var code = response.status;
if (code == 404) {
final fetchResponse = response as FetchResponse;
if (fetchResponse.status != 200) {
disableSearch();
return;
}

var text = await response.text;
final text = await fetchResponse.text;
final index = Index.fromJson(text);

// Navigate to the first result from the 'search' query parameter
Expand Down
2 changes: 1 addition & 1 deletion web/sig.txt
Original file line number Diff line number Diff line change
@@ -1 +1 @@
8C67B39F09940FC20D8C13F6BBE0B1EE
157D433EE554B00A24CAF73333958091
15 changes: 5 additions & 10 deletions web/web_interop.dart
Original file line number Diff line number Diff line change
Expand Up @@ -2,22 +2,17 @@
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

import 'dart:js_util' as js_util;

import 'package:js/js.dart';
import 'dart:js_interop';

@JS('Response')
@staticInterop
class FetchResponse {}
final class FetchResponse {}

extension FetchResponseExtension on FetchResponse {
external int get status;

@JS('text')
external Promise _text();
Future<String> get text => js_util.promiseToFuture(_text());
external JSPromise _text();
Future<String> get text async =>
((await _text().toDart) as JSString).toString();
}

@JS()
@staticInterop
class Promise {}