OLD | NEW |
1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file |
2 // for details. All rights reserved. Use of this source code is governed by a | 2 // for details. All rights reserved. Use of this source code is governed by a |
3 // BSD-style license that can be found in the LICENSE file. | 3 // BSD-style license that can be found in the LICENSE file. |
4 | 4 |
5 /** | 5 /** |
6 * To generate docs for a library, run this script with the path to an | 6 * To generate docs for a library, run this script with the path to an |
7 * entrypoint .dart file, like: | 7 * entrypoint .dart file, like: |
8 * | 8 * |
9 * $ dart dartdoc.dart foo.dart | 9 * $ dart dartdoc.dart foo.dart |
10 * | 10 * |
11 * This will create a "docs" directory with the docs for your libraries. To | 11 * This will create a "docs" directory with the docs for your libraries. To |
12 * create these beautiful docs, dartdoc parses your library and every library | 12 * create these beautiful docs, dartdoc parses your library and every library |
13 * it imports (recursively). From each library, it parses all classes and | 13 * it imports (recursively). From each library, it parses all classes and |
14 * members, finds the associated doc comments and builds crosslinked docs from | 14 * members, finds the associated doc comments and builds crosslinked docs from |
15 * them. | 15 * them. |
16 */ | 16 */ |
17 library dartdoc; | 17 library dartdoc; |
18 | 18 |
19 import 'dart:async'; | 19 import 'dart:async'; |
20 import 'dart:io'; | 20 import 'dart:io'; |
21 | 21 |
22 // TODO(rnystrom): Use "package:" URL (#4968). | 22 // TODO(rnystrom): Use "package:" URL (#4968). |
23 import '../lib/dartdoc.dart'; | 23 import '../lib/dartdoc.dart'; |
| 24 import '../lib/src/dartdoc/utils.dart'; |
24 import 'package:args/args.dart'; | 25 import 'package:args/args.dart'; |
25 import 'package:pathos/path.dart' as path; | 26 import 'package:pathos/path.dart' as path; |
26 | 27 |
27 /** | 28 /** |
28 * Run this from the `lib/_internal/dartdoc` directory. | 29 * Run this from the `lib/_internal/dartdoc` directory. |
29 */ | 30 */ |
30 main() { | 31 main() { |
31 // Need this because ArgParser.getUsage doesn't show command invocation. | 32 // Need this because ArgParser.getUsage doesn't show command invocation. |
32 final USAGE = 'Usage dartdoc [options] <entrypoint(s)>\n[options] include:'; | 33 final USAGE = 'Usage dartdoc [options] <entrypoint(s)>\n[options] include:'; |
33 | 34 |
(...skipping 147 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
181 | 182 |
182 dartdoc.dartdocPath = libPath.append('lib/_internal/dartdoc'); | 183 dartdoc.dartdocPath = libPath.append('lib/_internal/dartdoc'); |
183 | 184 |
184 if (args.isEmpty) { | 185 if (args.isEmpty) { |
185 print('No arguments provided.'); | 186 print('No arguments provided.'); |
186 print(USAGE); | 187 print(USAGE); |
187 print(argParser.getUsage()); | 188 print(argParser.getUsage()); |
188 exit(1); | 189 exit(1); |
189 } | 190 } |
190 | 191 |
191 final entrypoints = <String>[]; | 192 final entrypoints = <Uri>[]; |
192 try { | 193 try { |
193 final option = argParser.parse(args); | 194 final option = argParser.parse(args); |
194 | 195 |
195 // This checks to see if the root of all entrypoints is the same. | 196 // This checks to see if the root of all entrypoints is the same. |
196 // If it is not, then we display a warning, as package imports might fail. | 197 // If it is not, then we display a warning, as package imports might fail. |
197 var entrypointRoot; | 198 var entrypointRoot; |
198 for (final entrypoint in option.rest) { | 199 for (final entrypoint in option.rest) { |
199 entrypoints.add(entrypoint); | 200 var uri = Uri.parse(entrypoint); |
| 201 if (uri.scheme == '') uri = pathToFileUri(entrypoint); |
| 202 entrypoints.add(uri); |
200 | 203 |
| 204 if (uri.scheme != 'file') continue; |
201 if (entrypointRoot == null) { | 205 if (entrypointRoot == null) { |
202 entrypointRoot = path.dirname(entrypoint); | 206 entrypointRoot = path.dirname(entrypoint); |
203 } else if (entrypointRoot != path.dirname(entrypoint)) { | 207 } else if (entrypointRoot != path.dirname(entrypoint)) { |
204 print('Warning: entrypoints are at different directories. "package:"' | 208 print('Warning: entrypoints are at different directories. "package:"' |
205 ' imports may fail.'); | 209 ' imports may fail.'); |
206 } | 210 } |
207 } | 211 } |
208 } on FormatException catch (e) { | 212 } on FormatException catch (e) { |
209 print(e.message); | 213 print(e.message); |
210 print(USAGE); | 214 print(USAGE); |
211 print(argParser.getUsage()); | 215 print(argParser.getUsage()); |
212 exit(1); | 216 exit(1); |
213 } | 217 } |
214 | 218 |
215 if (entrypoints.isEmpty) { | 219 if (entrypoints.isEmpty) { |
216 print('No entrypoints provided.'); | 220 print('No entrypoints provided.'); |
217 print(argParser.getUsage()); | 221 print(argParser.getUsage()); |
218 exit(1); | 222 exit(1); |
219 } | 223 } |
220 | 224 |
221 if (packageRoot == null) { | 225 if (packageRoot == null) packageRoot = _getPackageRoot(entrypoints); |
222 // Check if there's a `packages` directory in the entry point directory. | |
223 var script = path.normalize(path.absolute(entrypoints[0])); | |
224 var dir = path.join(path.dirname(script), 'packages/'); | |
225 if (new Directory(dir).existsSync()) { | |
226 packageRoot = dir; | |
227 } else { | |
228 // If there is not, then check if the entrypoint is somewhere in a `lib` | |
229 // directory. | |
230 dir = path.dirname(script); | |
231 var parts = path.split(dir); | |
232 var libDir = parts.lastIndexOf('lib'); | |
233 if (libDir > 0) { | |
234 packageRoot = path.join(path.joinAll(parts.take(libDir)), 'packages'); | |
235 } | |
236 } | |
237 } | |
238 | 226 |
239 cleanOutputDirectory(dartdoc.outputDir); | 227 cleanOutputDirectory(dartdoc.outputDir); |
240 | 228 |
241 // Start the analysis and documentation. | 229 // Start the analysis and documentation. |
242 dartdoc.documentLibraries(entrypoints, libPath, packageRoot) | 230 dartdoc.documentLibraries(entrypoints, libPath, packageRoot) |
243 .then((_) { | 231 .then((_) { |
244 print('Copying static files...'); | 232 print('Copying static files...'); |
245 Future.wait([ | 233 Future.wait([ |
246 // Prepare the dart2js script code and copy static resources. | 234 // Prepare the dart2js script code and copy static resources. |
247 // TODO(amouravski): move compileScript out and pre-generate the client | 235 // TODO(amouravski): move compileScript out and pre-generate the client |
248 // scripts. This takes a long time and the js hardly ever changes. | 236 // scripts. This takes a long time and the js hardly ever changes. |
249 compileScript(dartdoc.mode, dartdoc.outputDir, libPath), | 237 compileScript(dartdoc.mode, dartdoc.outputDir, libPath), |
250 copyDirectory(scriptDir.append('../static'), dartdoc.outputDir) | 238 copyDirectory(scriptDir.append('../static'), dartdoc.outputDir) |
251 ]); | 239 ]); |
252 }) | 240 }) |
253 .then((_) { | 241 .then((_) { |
254 print(dartdoc.status); | 242 print(dartdoc.status); |
255 if (dartdoc.totals == 0) { | 243 if (dartdoc.totals == 0) { |
256 exit(1); | 244 exit(1); |
257 } | 245 } |
258 }) | 246 }) |
259 .catchError((e) { | 247 .catchError((e) { |
260 print('Error: generation failed: ${e}'); | 248 print('Error: generation failed: ${e}'); |
261 dartdoc.cleanup(); | 249 dartdoc.cleanup(); |
262 exit(1); | 250 exit(1); |
263 }) | 251 }) |
264 .whenComplete(() => dartdoc.cleanup()); | 252 .whenComplete(() => dartdoc.cleanup()); |
265 } | 253 } |
| 254 |
| 255 String _getPackageRoot(List<Uri> entrypoints) { |
| 256 // Check if there's a `packages` directory in the entry point directory. |
| 257 var fileEntrypoint = entrypoints.firstWhere( |
| 258 (entrypoint) => entrypoint.scheme == 'file', |
| 259 orElse: () => null); |
| 260 if (fileEntrypoint != null) { |
| 261 var script = path.normalize(path.absolute(fileUriToPath(fileEntrypoint))); |
| 262 var dir = path.join(path.dirname(script), 'packages/'); |
| 263 if (new Directory(dir).existsSync()) return dir; |
| 264 } |
| 265 |
| 266 // If there is not, then check if the entrypoint is somewhere in a `lib` |
| 267 // directory. |
| 268 dir = path.dirname(script); |
| 269 var parts = path.split(dir); |
| 270 var libDir = parts.lastIndexOf('lib'); |
| 271 if (libDir > 0) { |
| 272 return path.join(path.joinAll(parts.take(libDir)), 'packages'); |
| 273 } else { |
| 274 return null; |
| 275 } |
| 276 } |
OLD | NEW |