Skip to content

Commit afeea82

Browse files
devoncarewdevoncarew
authored
add support for a --footer-text flag (#1377)
* add support for a --footer-text flag * update the changelog
1 parent 94026a6 commit afeea82

File tree

569 files changed

+1235
-2290
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

569 files changed

+1235
-2290
lines changed

‎CHANGELOG.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
## unreleased
2+
3+
* added a new `--footer-text` command-line option, to allow adding additional
4+
text in the package name and copyright section of the footer
5+
16
## 0.10.0
27

38
* fix canonicalization problems and related issues introduced or not addressed

‎bin/dartdoc.dart

Lines changed: 25 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,16 @@ main(List<String> arguments) async {
7272
List<String> includeExternals = args['include-external'] as List<String>;
7373

7474
String url = args['hosted-url'];
75+
76+
List<String> headerFilePaths =
77+
args['header'].map(_resolveTildePath).toList() as List<String>;
78+
for (String headerFilePath in headerFilePaths) {
79+
if (!new File(headerFilePath).existsSync()) {
80+
stderr.write(" Error: unable to locate header file: ${headerFilePath}.");
81+
exit(1);
82+
}
83+
}
84+
7585
List<String> footerFilePaths =
7686
args['footer'].map(_resolveTildePath).toList() as List<String>;
7787
for (String footerFilePath in footerFilePaths) {
@@ -80,11 +90,13 @@ main(List<String> arguments) async {
8090
exit(1);
8191
}
8292
}
83-
List<String> headerFilePaths =
84-
args['header'].map(_resolveTildePath).toList() as List<String>;
85-
for (String headerFilePath in footerFilePaths) {
86-
if (!new File(headerFilePath).existsSync()) {
87-
stderr.write(" Error: unable to locate header file: ${headerFilePath}.");
93+
94+
List<String> footerTextFilePaths =
95+
args['footer-text'].map(_resolveTildePath).toList() as List<String>;
96+
for (String footerFilePath in footerTextFilePaths) {
97+
if (!new File(footerFilePath).existsSync()) {
98+
stderr.write(
99+
" Error: unable to locate footer-text file: ${footerFilePath}.");
88100
exit(1);
89101
}
90102
}
@@ -125,8 +137,10 @@ main(List<String> arguments) async {
125137
"${outputDir.absolute.path}${Platform.pathSeparator}");
126138
print('');
127139

128-
var generators = await initGenerators(
129-
url, headerFilePaths, footerFilePaths, args['rel-canonical-prefix'],
140+
var generators = await initGenerators(url, args['rel-canonical-prefix'],
141+
headerFilePaths: headerFilePaths,
142+
footerFilePaths: footerFilePaths,
143+
footerTextFilePaths: footerTextFilePaths,
130144
faviconPath: args['favicon'],
131145
useCategories: args['use-categories'],
132146
prettyIndexJson: args['pretty-index-json']);
@@ -201,6 +215,10 @@ ArgParser _createArgsParser() {
201215
allowMultiple: true,
202216
splitCommas: true,
203217
help: 'paths to footer files containing HTML text.');
218+
parser.addOption('footer-text',
219+
allowMultiple: true,
220+
splitCommas: true,
221+
help: 'paths to footer-text files (optional text next to the copyright).');
204222
parser.addOption('exclude',
205223
allowMultiple: true, splitCommas: true, help: 'Library names to ignore.');
206224
parser.addOption('include',

‎lib/dartdoc.dart

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -47,9 +47,11 @@ const String version = '0.10.0';
4747
final String defaultOutDir = path.join('doc', 'api');
4848

4949
/// Initialize and setup the generators.
50-
Future<List<Generator>> initGenerators(String url, List<String> headerFilePaths,
51-
List<String> footerFilePaths, String relCanonicalPrefix,
52-
{String faviconPath,
50+
Future<List<Generator>> initGenerators(String url, String relCanonicalPrefix,
51+
{List<String> headerFilePaths,
52+
List<String> footerFilePaths,
53+
List<String> footerTextFilePaths,
54+
String faviconPath,
5355
bool useCategories: false,
5456
bool prettyIndexJson: false}) async {
5557
var options = new HtmlGeneratorOptions(
@@ -65,6 +67,7 @@ Future<List<Generator>> initGenerators(String url, List<String> headerFilePaths,
6567
options: options,
6668
headers: headerFilePaths,
6769
footers: footerFilePaths,
70+
footerTexts: footerTextFilePaths,
6871
)
6972
];
7073
}

‎lib/src/html/html_generator.dart

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -46,9 +46,11 @@ class HtmlGenerator extends Generator {
4646
static Future<HtmlGenerator> create(
4747
{HtmlGeneratorOptions options,
4848
List<String> headers,
49-
List<String> footers}) async {
50-
var templates =
51-
await Templates.create(headerPaths: headers, footerPaths: footers);
49+
List<String> footers, List<String> footerTexts}) async {
50+
var templates = await Templates.create(
51+
headerPaths: headers,
52+
footerPaths: footers,
53+
footerTextPaths: footerTexts);
5254

5355
return new HtmlGenerator._(
5456
options ?? new HtmlGeneratorOptions(), templates);

‎lib/src/html/templates.dart

Lines changed: 24 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -33,33 +33,40 @@ const _partials = const <String>[
3333
'accessor_setter'
3434
];
3535

36-
Future<Map<String, String>> _loadPartials(
37-
List<String> headerPaths, List<String> footerPaths) async {
36+
Future<Map<String, String>> _loadPartials(List<String> headerPaths,
37+
List<String> footerPaths, List<String> footerTextPaths) async {
38+
final String headerPlaceholder = '<!-- header placeholder -->';
39+
final String footerPlaceholder = '<!-- footer placeholder -->';
40+
final String footerTextPlaceholder = '<!-- footer-text placeholder -->';
41+
3842
headerPaths ??= [];
3943
footerPaths ??= [];
44+
footerTextPaths ??= [];
4045

4146
var partials = <String, String>{};
4247

4348
Future<String> _loadPartial(String templatePath) async {
4449
String template = await _getTemplateFile(templatePath);
45-
if (templatePath.contains('_head') && headerPaths.isNotEmpty) {
50+
51+
if (templatePath.contains('_head')) {
4652
String headerValue = headerPaths
4753
.map((path) => new File(path).readAsStringSync())
4854
.join('\n');
49-
template =
50-
template.replaceAll('<!-- Header Placeholder -->', headerValue);
51-
template =
52-
template.replaceAll(' <!-- Do not remove placeholder -->\n', '');
55+
template = template.replaceAll(headerPlaceholder, headerValue);
5356
}
54-
if (templatePath.contains('_footer') && footerPaths.isNotEmpty) {
57+
58+
if (templatePath.contains('_footer')) {
5559
String footerValue = footerPaths
5660
.map((path) => new File(path).readAsStringSync())
5761
.join('\n');
58-
template =
59-
template.replaceAll('<!-- Footer Placeholder -->', footerValue);
60-
template =
61-
template.replaceAll(' <!-- Do not remove placeholder -->\n', '');
62+
template = template.replaceAll(footerPlaceholder, footerValue);
63+
64+
String footerTextValue = footerTextPaths
65+
.map((path) => new File(path).readAsStringSync())
66+
.join('\n');
67+
template = template.replaceAll(footerTextPlaceholder, footerTextValue);
6268
}
69+
6370
return template;
6471
}
6572

@@ -88,8 +95,11 @@ class Templates {
8895
final TemplateRenderer typeDefTemplate;
8996

9097
static Future<Templates> create(
91-
{List<String> headerPaths, List<String> footerPaths}) async {
92-
var partials = await _loadPartials(headerPaths, footerPaths);
98+
{List<String> headerPaths,
99+
List<String> footerPaths,
100+
List<String> footerTextPaths}) async {
101+
var partials =
102+
await _loadPartials(headerPaths, footerPaths, footerTextPaths);
93103

94104
String _partial(String name) {
95105
String partial = partials[name];

‎lib/templates/_footer.html

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,8 @@
1818
<span class="copyright no-break">
1919
<a href="http://creativecommons.org/licenses/by-sa/4.0/">cc license</a>
2020
</span>
21+
22+
<!-- footer-text placeholder -->
2123
</p>
2224
</div>
2325
</div>
@@ -28,8 +30,7 @@
2830
<script src="static-assets/prettify.js"></script>
2931
<script src="static-assets/URI.js"></script>
3032
<script src="static-assets/script.js"></script>
31-
<!-- Do not remove placeholder -->
32-
<!-- Footer Placeholder -->
33+
<!-- footer placeholder -->
3334

3435
</body>
3536

‎lib/templates/_head.html

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,7 @@
2323
<link rel="stylesheet" href="static-assets/styles.css">
2424
<link rel="icon" href="static-assets/favicon.png">
2525

26-
<!-- Do not remove placeholder -->
27-
<!-- Header Placeholder -->
26+
<!-- header placeholder -->
2827
</head>
2928

3029
<body>

‎test/compare_output_test.dart

Lines changed: 44 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ import 'dart:convert';
88
import 'dart:io';
99
import 'dart:mirrors';
1010

11-
import 'package:path/path.dart' as p;
11+
import 'package:path/path.dart' as path;
1212
import 'package:test/test.dart';
1313

1414
const List<String> _filesToIgnore = const <String>['.DS_Store'];
@@ -21,16 +21,17 @@ Uri get _currentFileUri =>
2121
(reflect(main) as ClosureMirror).function.location.sourceUri;
2222

2323
String get _testPackageDocsPath =>
24-
p.fromUri(_currentFileUri.resolve('../testing/test_package_docs'));
24+
path.fromUri(_currentFileUri.resolve('../testing/test_package_docs'));
2525

2626
String get _testPackagePath =>
27-
p.fromUri(_currentFileUri.resolve('../testing/test_package'));
27+
path.fromUri(_currentFileUri.resolve('../testing/test_package'));
2828

2929
void main() {
3030
group('compare outputs', () {
3131
Directory tempDir;
3232

33-
var dartdocBin = p.fromUri(_currentFileUri.resolve('../bin/dartdoc.dart'));
33+
var dartdocBin =
34+
path.fromUri(_currentFileUri.resolve('../bin/dartdoc.dart'));
3435

3536
setUp(() {
3637
tempDir = Directory.systemTemp.createTempSync('dartdoc.test.');
@@ -99,8 +100,8 @@ void main() {
99100
'diff',
100101
'--no-index',
101102
'--no-color',
102-
p.join(_testPackageDocsPath, k),
103-
p.join(tempDir.path, k)
103+
path.join(_testPackageDocsPath, k),
104+
path.join(tempDir.path, k)
104105
];
105106
result = Process.runSync(gitBinName, args);
106107
assert(result.exitCode != 0);
@@ -149,6 +150,34 @@ void main() {
149150
}
150151
});
151152

153+
test('--footer-text includes text', () {
154+
String footerTextPath =
155+
path.join(Directory.systemTemp.path, 'footer.txt');
156+
new File(footerTextPath).writeAsStringSync(' footer text include ');
157+
158+
var args = <String>[
159+
dartdocBin,
160+
'--footer-text=${footerTextPath}',
161+
'--include',
162+
'ex',
163+
'--output',
164+
tempDir.path
165+
];
166+
167+
var result = Process.runSync(Platform.resolvedExecutable, args,
168+
workingDirectory: _testPackagePath);
169+
170+
if (result.exitCode != 0) {
171+
print(result.exitCode);
172+
print(result.stdout);
173+
print(result.stderr);
174+
fail('dartdoc failed');
175+
}
176+
177+
File outFile = new File(path.join(tempDir.path, 'index.html'));
178+
expect(outFile.readAsStringSync(), contains('footer text include'));
179+
});
180+
152181
test('Check dartdoc generation with crossdart', () {
153182
var args = <String>[
154183
dartdocBin,
@@ -177,23 +206,23 @@ Map<String, String> _parseOutput(
177206
Match match = _nameStatusLineRegexp.firstMatch(line);
178207

179208
var type = match[1];
180-
var path = match[2];
209+
var p = match[2];
181210

182-
if (_filesToIgnore.any((i) => p.basename(path) == i)) {
211+
if (_filesToIgnore.any((i) => path.basename(p) == i)) {
183212
continue;
184213
}
185214

186215
if (type == 'A') {
187-
expect(p.isWithin(tempPath, path), isTrue,
188-
reason: '`$path` should be within $tempPath');
189-
path = p.relative(path, from: tempPath);
216+
expect(path.isWithin(tempPath, p), isTrue,
217+
reason: '`$p` should be within $tempPath');
218+
p = path.relative(p, from: tempPath);
190219
} else {
191-
expect(p.isWithin(sourcePath, path), isTrue,
192-
reason: '`$path` should be within $sourcePath');
193-
path = p.relative(path, from: sourcePath);
220+
expect(path.isWithin(sourcePath, p), isTrue,
221+
reason: '`$p` should be within $sourcePath');
222+
p = path.relative(p, from: sourcePath);
194223
}
195224

196-
values[path] = type;
225+
values[p] = type;
197226
}
198227

199228
return values;

‎testing/test_package_docs/anonymous_library/anonymous_library-library.html

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,6 @@
1515
<link rel="stylesheet" href="static-assets/styles.css">
1616
<link rel="icon" href="static-assets/favicon.png">
1717

18-
<!-- Do not remove placeholder -->
19-
<!-- Header Placeholder -->
2018
</head>
2119

2220
<body>
@@ -145,6 +143,7 @@ <h5>anonymous_library</h5>
145143
<span class="copyright no-break">
146144
<a href="http://creativecommons.org/licenses/by-sa/4.0/">cc license</a>
147145
</span>
146+
148147
</p>
149148
</div>
150149
</div>
@@ -155,8 +154,7 @@ <h5>anonymous_library</h5>
155154
<script src="static-assets/prettify.js"></script>
156155
<script src="static-assets/URI.js"></script>
157156
<script src="static-assets/script.js"></script>
158-
<!-- Do not remove placeholder -->
159-
<!-- Footer Placeholder -->
157+
160158

161159
</body>
162160

‎testing/test_package_docs/anonymous_library/doesStuff.html

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,6 @@
1515
<link rel="stylesheet" href="static-assets/styles.css">
1616
<link rel="icon" href="static-assets/favicon.png">
1717

18-
<!-- Do not remove placeholder -->
19-
<!-- Header Placeholder -->
2018
</head>
2119

2220
<body>
@@ -111,6 +109,7 @@ <h5><a href="anonymous_library/anonymous_library-library.html">anonymous_library
111109
<span class="copyright no-break">
112110
<a href="http://creativecommons.org/licenses/by-sa/4.0/">cc license</a>
113111
</span>
112+
114113
</p>
115114
</div>
116115
</div>
@@ -121,8 +120,7 @@ <h5><a href="anonymous_library/anonymous_library-library.html">anonymous_library
121120
<script src="static-assets/prettify.js"></script>
122121
<script src="static-assets/URI.js"></script>
123122
<script src="static-assets/script.js"></script>
124-
<!-- Do not remove placeholder -->
125-
<!-- Footer Placeholder -->
123+
126124

127125
</body>
128126

‎testing/test_package_docs/another_anonymous_lib/another_anonymous_lib-library.html

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,6 @@
1515
<link rel="stylesheet" href="static-assets/styles.css">
1616
<link rel="icon" href="static-assets/favicon.png">
1717

18-
<!-- Do not remove placeholder -->
19-
<!-- Header Placeholder -->
2018
</head>
2119

2220
<body>
@@ -145,6 +143,7 @@ <h5>another_anonymous_lib</h5>
145143
<span class="copyright no-break">
146144
<a href="http://creativecommons.org/licenses/by-sa/4.0/">cc license</a>
147145
</span>
146+
148147
</p>
149148
</div>
150149
</div>
@@ -155,8 +154,7 @@ <h5>another_anonymous_lib</h5>
155154
<script src="static-assets/prettify.js"></script>
156155
<script src="static-assets/URI.js"></script>
157156
<script src="static-assets/script.js"></script>
158-
<!-- Do not remove placeholder -->
159-
<!-- Footer Placeholder -->
157+
160158

161159
</body>
162160

0 commit comments

Comments
 (0)