Skip to content

Commit 7e503c1

Browse files
srawlinssrawlins
authored
Introduce a new URL for library pages, at index.html (#3895)
Fixes #1346 This "moves" the URL of each library from, e.g. 'package-two_lib2/package-two_lib2-library.html' to 'package-two_lib2/index.html', such that we can have links with 'package-two_lib2'. The old URLs are preserved via redirecting HTML files. (HTTP redirects are more standard and recommended, but dartdoc does not contain an HTTP server; HTTP redirects could be implemented at the hosting server, which is different for different doc hosts (Google Storage, Firebase, ...). Instead we use simpler HTML redirects. In fact, a given backend host could use the HTML redirecting files as a database to inform HTTP redirect rules, that need to be implemented differently for each backend. So dartdoc now produces redirecting files, but a given backend could instead return an HTTP 301 Permanent Redirect response when requesting one of the redirecting files.) This adds a negligible number of files (1 per documented library), and a negligible number of bytes (tiny redirect files), but actually is probably a net negative in terms of bytes, as many links are now shortened, removing the HTML file name of library URLs.
1 parent 80c6f18 commit 7e503c1

23 files changed

+1940
-1678
lines changed

‎lib/resources/docs.dart.js

Lines changed: 1613 additions & 1569 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎lib/resources/docs.dart.js.map

Lines changed: 6 additions & 6 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎lib/src/generator/generator_backend.dart

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -179,11 +179,14 @@ abstract class GeneratorBackend {
179179
runtimeStats.incrementAccumulator('writtenFunctionFileCount');
180180
}
181181

182-
/// Emits documentation content for the [library].
182+
/// Emits documentation content for the [library], and the content for the
183+
/// library's previous location (which just redirects to the new location).
183184
void generateLibrary(PackageGraph packageGraph, Library library) {
184185
var data = LibraryTemplateData(options, packageGraph, library);
185186
var content = templates.renderLibrary(data);
187+
var redirectContent = templates.renderLibraryRedirect(data);
186188
write(writer, library.filePath, data, content);
189+
write(writer, library.redirectingPath, data, redirectContent);
187190
runtimeStats.incrementAccumulator('writtenLibraryFileCount');
188191
}
189192

‎lib/src/generator/templates.aot_renderers_for_html.dart

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1137,6 +1137,40 @@ String renderLibrary(LibraryTemplateData context0) {
11371137
return buffer.toString();
11381138
}
11391139

1140+
String renderLibraryRedirect(LibraryTemplateData context0) {
1141+
final buffer = StringBuffer();
1142+
buffer.write('''<!DOCTYPE html>
1143+
<html lang="en">
1144+
<head>
1145+
<link rel="canonical" href="''');
1146+
if (context0.useBaseHref) {
1147+
var context1 = context0.htmlBase;
1148+
buffer.write(context0.htmlBase);
1149+
}
1150+
buffer.writeEscaped(context0.self.href);
1151+
buffer.write('''" />
1152+
<meta http-equiv="refresh" content="0; url=''');
1153+
if (context0.useBaseHref) {
1154+
var context2 = context0.htmlBase;
1155+
buffer.write(context0.htmlBase);
1156+
}
1157+
buffer.writeEscaped(context0.self.href);
1158+
buffer.write('''" />
1159+
</head>
1160+
<body>
1161+
<p><a href="''');
1162+
if (context0.useBaseHref) {
1163+
var context3 = context0.htmlBase;
1164+
buffer.write(context0.htmlBase);
1165+
}
1166+
buffer.writeEscaped(context0.self.href);
1167+
buffer.write('''">New URL</a></p>
1168+
</body>
1169+
</html>''');
1170+
1171+
return buffer.toString();
1172+
}
1173+
11401174
String renderMethod(MethodTemplateData context0) {
11411175
final buffer = StringBuffer();
11421176
buffer.write(_renderMethod_partial_head_0(context0));

‎lib/src/generator/templates.dart

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,8 @@
2222
@Renderer(#renderFunction, Context<FunctionTemplateData>(), 'function')
2323
@Renderer(#renderIndex, Context<PackageTemplateData>(), 'index')
2424
@Renderer(#renderLibrary, Context<LibraryTemplateData>(), 'library')
25+
@Renderer(
26+
#renderLibraryRedirect, Context<LibraryTemplateData>(), 'library_redirect')
2527
@Renderer(#renderMethod, Context<MethodTemplateData>(), 'method')
2628
@Renderer(#renderMixin, Context<MixinTemplateData>(), 'mixin')
2729
@Renderer(#renderProperty, Context<PropertyTemplateData>(), 'property')
@@ -99,6 +101,7 @@ abstract class Templates {
99101
String renderFunction(FunctionTemplateData context);
100102
String renderIndex(PackageTemplateData context);
101103
String renderLibrary(LibraryTemplateData context);
104+
String renderLibraryRedirect(LibraryTemplateData context);
102105
String renderMethod(MethodTemplateData context);
103106
String renderMixin(MixinTemplateData context);
104107
String renderProperty(PropertyTemplateData context);
@@ -174,6 +177,10 @@ class HtmlAotTemplates implements Templates {
174177
String renderLibrary(LibraryTemplateData context) =>
175178
aot_renderers_for_html.renderLibrary(context);
176179

180+
@override
181+
String renderLibraryRedirect(LibraryTemplateData context) =>
182+
aot_renderers_for_html.renderLibraryRedirect(context);
183+
177184
@override
178185
String renderMethod(MethodTemplateData context) =>
179186
aot_renderers_for_html.renderMethod(context);
@@ -251,6 +258,10 @@ class RuntimeTemplates implements Templates {
251258
String renderLibrary(LibraryTemplateData context) =>
252259
runtime_renderers.renderLibrary(context, _libraryTemplate);
253260

261+
@override
262+
String renderLibraryRedirect(LibraryTemplateData context) =>
263+
runtime_renderers.renderLibraryRedirect(context, _libraryTemplate);
264+
254265
@override
255266
String renderMethod(MethodTemplateData context) =>
256267
runtime_renderers.renderMethod(context, _methodTemplate);

‎lib/src/generator/templates.runtime_renderers.dart

Lines changed: 59 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -2760,28 +2760,6 @@ class _Renderer_Container extends RendererBase<Container> {
27602760
parent: r);
27612761
},
27622762
),
2763-
'filePath': Property(
2764-
getValue: (CT_ c) => c.filePath,
2765-
renderVariable:
2766-
(CT_ c, Property<CT_> self, List<String> remainingNames) {
2767-
if (remainingNames.isEmpty) {
2768-
return self.getValue(c).toString();
2769-
}
2770-
var name = remainingNames.first;
2771-
var nextProperty =
2772-
_Renderer_String.propertyMap().getValue(name);
2773-
return nextProperty.renderVariable(
2774-
self.getValue(c) as String,
2775-
nextProperty,
2776-
[...remainingNames.skip(1)]);
2777-
},
2778-
isNullValue: (CT_ c) => false,
2779-
renderValue: (CT_ c, RendererBase<CT_> r,
2780-
List<MustachioNode> ast, StringSink sink) {
2781-
_render_String(c.filePath, ast, r.template, sink,
2782-
parent: r);
2783-
},
2784-
),
27852763
'hasAvailableInstanceFields': Property(
27862764
getValue: (CT_ c) => c.hasAvailableInstanceFields,
27872765
renderVariable: (CT_ c, Property<CT_> self,
@@ -4283,6 +4261,28 @@ class _Renderer_Enum extends RendererBase<Enum> {
42834261
parent: r, getters: _invisibleGetters['EnumElement']!);
42844262
},
42854263
),
4264+
'fileName': Property(
4265+
getValue: (CT_ c) => c.fileName,
4266+
renderVariable:
4267+
(CT_ c, Property<CT_> self, List<String> remainingNames) {
4268+
if (remainingNames.isEmpty) {
4269+
return self.getValue(c).toString();
4270+
}
4271+
var name = remainingNames.first;
4272+
var nextProperty =
4273+
_Renderer_String.propertyMap().getValue(name);
4274+
return nextProperty.renderVariable(
4275+
self.getValue(c) as String,
4276+
nextProperty,
4277+
[...remainingNames.skip(1)]);
4278+
},
4279+
isNullValue: (CT_ c) => false,
4280+
renderValue: (CT_ c, RendererBase<CT_> r,
4281+
List<MustachioNode> ast, StringSink sink) {
4282+
_render_String(c.fileName, ast, r.template, sink,
4283+
parent: r);
4284+
},
4285+
),
42864286
'hasPublicEnumValues': Property(
42874287
getValue: (CT_ c) => c.hasPublicEnumValues,
42884288
renderVariable: (CT_ c, Property<CT_> self,
@@ -8430,6 +8430,28 @@ class _Renderer_Library extends RendererBase<Library> {
84308430
parent: r));
84318431
},
84328432
),
8433+
'redirectingPath': Property(
8434+
getValue: (CT_ c) => c.redirectingPath,
8435+
renderVariable:
8436+
(CT_ c, Property<CT_> self, List<String> remainingNames) {
8437+
if (remainingNames.isEmpty) {
8438+
return self.getValue(c).toString();
8439+
}
8440+
var name = remainingNames.first;
8441+
var nextProperty =
8442+
_Renderer_String.propertyMap().getValue(name);
8443+
return nextProperty.renderVariable(
8444+
self.getValue(c) as String,
8445+
nextProperty,
8446+
[...remainingNames.skip(1)]);
8447+
},
8448+
isNullValue: (CT_ c) => false,
8449+
renderValue: (CT_ c, RendererBase<CT_> r,
8450+
List<MustachioNode> ast, StringSink sink) {
8451+
_render_String(c.redirectingPath, ast, r.template, sink,
8452+
parent: r);
8453+
},
8454+
),
84338455
'referenceChildren': Property(
84348456
getValue: (CT_ c) => c.referenceChildren,
84358457
renderVariable: (CT_ c, Property<CT_> self,
@@ -8795,6 +8817,12 @@ class _Renderer_LibraryTemplateData extends RendererBase<LibraryTemplateData> {
87958817
}
87968818
}
87978819

8820+
String renderLibraryRedirect(LibraryTemplateData context, Template template) {
8821+
var buffer = StringBuffer();
8822+
_render_LibraryTemplateData(context, template.ast, template, buffer);
8823+
return buffer.toString();
8824+
}
8825+
87988826
class _Renderer_Locatable extends RendererBase<Locatable> {
87998827
static final Map<Type, Object> _propertyMapCache = {};
88008828
static Map<String, Property<CT_>> propertyMap<CT_ extends Locatable>() =>
@@ -11037,8 +11065,8 @@ class _Renderer_ModelFunctionTyped extends RendererBase<ModelFunctionTyped> {
1103711065
parent: r);
1103811066
},
1103911067
),
11040-
'filePath': Property(
11041-
getValue: (CT_ c) => c.filePath,
11068+
'fileName': Property(
11069+
getValue: (CT_ c) => c.fileName,
1104211070
renderVariable:
1104311071
(CT_ c, Property<CT_> self, List<String> remainingNames) {
1104411072
if (remainingNames.isEmpty) {
@@ -11055,7 +11083,7 @@ class _Renderer_ModelFunctionTyped extends RendererBase<ModelFunctionTyped> {
1105511083
isNullValue: (CT_ c) => false,
1105611084
renderValue: (CT_ c, RendererBase<CT_> r,
1105711085
List<MustachioNode> ast, StringSink sink) {
11058-
_render_String(c.filePath, ast, r.template, sink,
11086+
_render_String(c.fileName, ast, r.template, sink,
1105911087
parent: r);
1106011088
},
1106111089
),
@@ -12231,7 +12259,7 @@ class _Renderer_Package extends RendererBase<Package> {
1223112259
}
1223212260
}
1223312261

12234-
String renderIndex(PackageTemplateData context, Template template) {
12262+
String renderError(PackageTemplateData context, Template template) {
1223512263
var buffer = StringBuffer();
1223612264
_render_PackageTemplateData(context, template.ast, template, buffer);
1223712265
return buffer.toString();
@@ -12469,13 +12497,13 @@ class _Renderer_PackageTemplateData extends RendererBase<PackageTemplateData> {
1246912497
}
1247012498
}
1247112499

12472-
String renderSearchPage(PackageTemplateData context, Template template) {
12500+
String renderIndex(PackageTemplateData context, Template template) {
1247312501
var buffer = StringBuffer();
1247412502
_render_PackageTemplateData(context, template.ast, template, buffer);
1247512503
return buffer.toString();
1247612504
}
1247712505

12478-
String renderError(PackageTemplateData context, Template template) {
12506+
String renderSearchPage(PackageTemplateData context, Template template) {
1247912507
var buffer = StringBuffer();
1248012508
_render_PackageTemplateData(context, template.ast, template, buffer);
1248112509
return buffer.toString();
@@ -14653,28 +14681,6 @@ class _Renderer_TopLevelVariable extends RendererBase<TopLevelVariable> {
1465314681
parent: r);
1465414682
},
1465514683
),
14656-
'filePath': Property(
14657-
getValue: (CT_ c) => c.filePath,
14658-
renderVariable:
14659-
(CT_ c, Property<CT_> self, List<String> remainingNames) {
14660-
if (remainingNames.isEmpty) {
14661-
return self.getValue(c).toString();
14662-
}
14663-
var name = remainingNames.first;
14664-
var nextProperty =
14665-
_Renderer_String.propertyMap().getValue(name);
14666-
return nextProperty.renderVariable(
14667-
self.getValue(c) as String,
14668-
nextProperty,
14669-
[...remainingNames.skip(1)]);
14670-
},
14671-
isNullValue: (CT_ c) => false,
14672-
renderValue: (CT_ c, RendererBase<CT_> r,
14673-
List<MustachioNode> ast, StringSink sink) {
14674-
_render_String(c.filePath, ast, r.template, sink,
14675-
parent: r);
14676-
},
14677-
),
1467814684
'getter': Property(
1467914685
getValue: (CT_ c) => c.getter,
1468014686
renderVariable:
@@ -15347,8 +15353,8 @@ class _Renderer_Typedef extends RendererBase<Typedef> {
1534715353
parent: r);
1534815354
},
1534915355
),
15350-
'filePath': Property(
15351-
getValue: (CT_ c) => c.filePath,
15356+
'fileName': Property(
15357+
getValue: (CT_ c) => c.fileName,
1535215358
renderVariable:
1535315359
(CT_ c, Property<CT_> self, List<String> remainingNames) {
1535415360
if (remainingNames.isEmpty) {
@@ -15365,7 +15371,7 @@ class _Renderer_Typedef extends RendererBase<Typedef> {
1536515371
isNullValue: (CT_ c) => false,
1536615372
renderValue: (CT_ c, RendererBase<CT_> r,
1536715373
List<MustachioNode> ast, StringSink sink) {
15368-
_render_String(c.filePath, ast, r.template, sink,
15374+
_render_String(c.fileName, ast, r.template, sink,
1536915375
parent: r);
1537015376
},
1537115377
),

‎lib/src/model/container.dart

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -232,9 +232,6 @@ abstract class Container extends ModelElement
232232
@override
233233
Iterable<CommentReferable> get referenceParents => [library];
234234

235-
@override
236-
String get filePath => '${canonicalLibraryOrThrow.dirName}/$fileName';
237-
238235
/// The full path of this element's sidebar file.
239236
String get sidebarPath;
240237

‎lib/src/model/enum.dart

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,10 @@ class Enum extends InheritingContainer with Constructable, MixedInTypes {
3131
...interfaceElements.expandInheritanceChain,
3232
];
3333

34+
@override
35+
// Prevent a collision with the library file.
36+
String get fileName => name == 'index' ? '$name-enum.html' : '$name.html';
37+
3438
@override
3539
String get sidebarPath =>
3640
'${canonicalLibraryOrThrow.dirName}/$name-enum-sidebar.html';

‎lib/src/model/getter_setter_combo.dart

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,11 @@ mixin GetterSetterCombo on ModelElement {
6161
String get name;
6262

6363
@override
64-
String get fileName => isConst ? '$name-constant.html' : '$name.html';
64+
String get fileName => isConst
65+
? '$name-constant.html'
66+
: name == 'index'
67+
? '$name-property.html'
68+
: '$name.html';
6569

6670
/// Whether this has a constant value which should be displayed.
6771
bool get hasConstantValueForDisplay => false;

‎lib/src/model/library.dart

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -199,7 +199,7 @@ class Library extends ModelElement
199199
String get filePath => '$dirName/$fileName';
200200

201201
@override
202-
String get fileName => '$dirName-library.html';
202+
String get fileName => 'index.html';
203203

204204
String get sidebarPath => '$dirName/$dirName-library-sidebar.html';
205205

@@ -216,9 +216,20 @@ class Library extends ModelElement
216216
if (!identical(canonicalModelElement, this)) {
217217
return canonicalModelElement?.href;
218218
}
219-
return '${package.baseHref}$filePath';
219+
// The file name for a library is 'index.html', so we just link to the
220+
// directory name. This keeps the URL looking short, _without_ the
221+
// 'index.html' in the URL.
222+
return '${package.baseHref}$dirName';
220223
}
221224

225+
/// The previous value of [filePath].
226+
///
227+
/// This path is used to write a file that ontains an HTML redirect (not an
228+
/// HTTP redirect) to a library's current [filePath].
229+
String get redirectingPath => '$dirName/$dirName-library.html';
230+
231+
/// Whether a libary is anonymous, either because it has no library directive
232+
/// or it has a library directive without a name.
222233
bool get isAnonymous => element.name.isEmpty;
223234

224235
@override

‎lib/src/model/model_element.dart

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -615,7 +615,7 @@ abstract class ModelElement
615615

616616
/// The full path of the output file in which this element will be primarily
617617
/// documented.
618-
String get filePath;
618+
String get filePath => '${canonicalLibraryOrThrow.dirName}/$fileName';
619619

620620
@override
621621
String get fullyQualifiedName =>

‎lib/src/model/model_function.dart

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,8 @@ class ModelFunctionTyped extends ModelElement with TypeParameters {
4949
Library get enclosingElement => library;
5050

5151
@override
52-
String get filePath => '${canonicalLibrary?.dirName}/$fileName';
52+
// Prevent a collision with the library file.
53+
String get fileName => name == 'index' ? '$name-function.html' : '$name.html';
5354

5455
@override
5556
String get aboveSidebarPath => canonicalLibraryOrThrow.sidebarPath;

‎lib/src/model/package.dart

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -136,9 +136,13 @@ class Package extends LibraryContainer
136136
bool get isPublic =>
137137
_isLocalPublicByDefault || libraries.any((l) => l.isPublic);
138138

139-
/// Return true if this is the default package, this is part of an embedder
140-
/// SDK, or if [DartdocOptionContext.autoIncludeDependencies] is true -- but
141-
/// only if the package was not excluded on the command line.
139+
/// Whether this package is local.
140+
///
141+
/// A package can be local in three ways:
142+
/// * this is the default package,
143+
/// * this is part of an embedder SDK, or
144+
/// * [DartdocOptionContext.autoIncludeDependencies] is true, and this
145+
/// package is not excluded with `exclude-packages`.
142146
bool get isLocal {
143147
// Do not document as local if we excluded this package by name.
144148
if (_isExcluded) return false;

0 commit comments

Comments
 (0)