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 import 'dart:uri'; | |
22 | 21 |
23 // TODO(rnystrom): Use "package:" URL (#4968). | 22 // TODO(rnystrom): Use "package:" URL (#4968). |
24 import '../lib/dartdoc.dart'; | 23 import '../lib/dartdoc.dart'; |
25 import '../lib/src/dartdoc/utils.dart'; | |
26 import 'package:args/args.dart'; | 24 import 'package:args/args.dart'; |
27 import 'package:pathos/path.dart' as path; | 25 import 'package:pathos/path.dart' as path; |
28 | 26 |
29 /** | 27 /** |
30 * Run this from the `lib/_internal/dartdoc` directory. | 28 * Run this from the `lib/_internal/dartdoc` directory. |
31 */ | 29 */ |
32 main() { | 30 main() { |
33 // Need this because ArgParser.getUsage doesn't show command invocation. | 31 // Need this because ArgParser.getUsage doesn't show command invocation. |
34 final USAGE = 'Usage dartdoc [options] <entrypoint(s)>\n[options] include:'; | 32 final USAGE = 'Usage dartdoc [options] <entrypoint(s)>\n[options] include:'; |
35 | 33 |
36 final args = new Options().arguments; | 34 final args = new Options().arguments; |
37 | 35 |
38 final dartdoc = new Dartdoc(); | 36 final dartdoc = new Dartdoc(); |
39 | 37 |
40 final argParser = new ArgParser(); | 38 final argParser = new ArgParser(); |
41 | 39 |
42 final Path libPath = scriptDir.append('../../../../'); | 40 final Path libPath = scriptDir.append('../../../../'); |
43 | 41 |
44 String packageRoot; | 42 Path packageRoot; |
45 | 43 |
46 argParser.addFlag('no-code', | 44 argParser.addFlag('no-code', |
47 help: 'Do not include source code in the documentation.', | 45 help: 'Do not include source code in the documentation.', |
48 defaultsTo: false, negatable: false, | 46 defaultsTo: false, negatable: false, |
49 callback: (noCode) => dartdoc.includeSource = !noCode); | 47 callback: (noCode) => dartdoc.includeSource = !noCode); |
50 | 48 |
51 argParser.addOption('mode', abbr: 'm', | 49 argParser.addOption('mode', abbr: 'm', |
52 help: 'Define how HTML pages are generated.', | 50 help: 'Define how HTML pages are generated.', |
53 allowed: ['static', 'live-nav'], allowedHelp: { | 51 allowed: ['static', 'live-nav'], allowedHelp: { |
54 'static': 'Generates completely static HTML containing\n' | 52 'static': 'Generates completely static HTML containing\n' |
(...skipping 106 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
161 dartdoc.excludedLibraries = allLibs; | 159 dartdoc.excludedLibraries = allLibs; |
162 } | 160 } |
163 }, allowMultiple: true); | 161 }, allowMultiple: true); |
164 | 162 |
165 argParser.addOption('package-root', | 163 argParser.addOption('package-root', |
166 help: 'Sets the package directory to the specified directory.\n' | 164 help: 'Sets the package directory to the specified directory.\n' |
167 'If omitted the package directory is the closest packages directory to' | 165 'If omitted the package directory is the closest packages directory to' |
168 ' the entrypoint.', | 166 ' the entrypoint.', |
169 callback: (packageDir) { | 167 callback: (packageDir) { |
170 if(packageDir != null) { | 168 if(packageDir != null) { |
171 packageRoot = packageDir; | 169 packageRoot = new Path(packageDir); |
172 } | 170 } |
173 }); | 171 }); |
174 | 172 |
175 // TODO(amouravski): This method is deprecated. Remove on April 22. | 173 // TODO(amouravski): This method is deprecated. Remove on April 22. |
176 argParser.addOption('pkg', | 174 argParser.addOption('pkg', |
177 help: 'Deprecated: same as --package-root.', | 175 help: 'Deprecated: same as --package-root.', |
178 callback: (packageDir) { | 176 callback: (packageDir) { |
179 if(packageDir != null) { | 177 if(packageDir != null) { |
180 packageRoot = packageDir; | 178 packageRoot = new Path(packageDir); |
181 } | 179 } |
182 }); | 180 }); |
183 | 181 |
184 dartdoc.dartdocPath = libPath.append('lib/_internal/dartdoc'); | 182 dartdoc.dartdocPath = libPath.append('lib/_internal/dartdoc'); |
185 | 183 |
186 if (args.isEmpty) { | 184 if (args.isEmpty) { |
187 print('No arguments provided.'); | 185 print('No arguments provided.'); |
188 print(USAGE); | 186 print(USAGE); |
189 print(argParser.getUsage()); | 187 print(argParser.getUsage()); |
190 exit(1); | 188 exit(1); |
191 } | 189 } |
192 | 190 |
193 final entrypoints = <Uri>[]; | 191 final entrypoints = <Path>[]; |
194 try { | 192 try { |
195 final option = argParser.parse(args); | 193 final option = argParser.parse(args); |
196 | 194 |
197 // This checks to see if the root of all entrypoints is the same. | 195 // This checks to see if the root of all entrypoints is the same. |
198 // If it is not, then we display a warning, as package imports might fail. | 196 // If it is not, then we display a warning, as package imports might fail. |
199 var entrypointRoot; | 197 var entrypointRoot; |
200 for (final entrypoint in option.rest) { | 198 for(final arg in option.rest) { |
201 var uri = Uri.parse(entrypoint); | 199 var entrypoint = new Path(arg); |
202 if (uri.scheme == '') uri = pathToFileUri(entrypoint); | 200 entrypoints.add(entrypoint); |
203 entrypoints.add(uri); | |
204 | 201 |
205 if (uri.scheme != 'file') continue; | |
206 if (entrypointRoot == null) { | 202 if (entrypointRoot == null) { |
207 entrypointRoot = path.dirname(entrypoint); | 203 entrypointRoot = entrypoint.directoryPath; |
208 } else if (entrypointRoot != path.dirname(entrypoint)) { | 204 } else if (entrypointRoot.toNativePath() != |
| 205 entrypoint.directoryPath.toNativePath()) { |
209 print('Warning: entrypoints are at different directories. "package:"' | 206 print('Warning: entrypoints are at different directories. "package:"' |
210 ' imports may fail.'); | 207 ' imports may fail.'); |
211 } | 208 } |
212 } | 209 } |
213 } on FormatException catch (e) { | 210 } on FormatException catch (e) { |
214 print(e.message); | 211 print(e.message); |
215 print(USAGE); | 212 print(USAGE); |
216 print(argParser.getUsage()); | 213 print(argParser.getUsage()); |
217 exit(1); | 214 exit(1); |
218 } | 215 } |
219 | 216 |
220 if (entrypoints.isEmpty) { | 217 if (entrypoints.isEmpty) { |
221 print('No entrypoints provided.'); | 218 print('No entrypoints provided.'); |
222 print(argParser.getUsage()); | 219 print(argParser.getUsage()); |
223 exit(1); | 220 exit(1); |
224 } | 221 } |
225 | 222 |
226 if (packageRoot == null) packageRoot = _getPackageRoot(entrypoints); | 223 if (packageRoot == null) { |
| 224 // Check if there's a `packages` directory in the entry point directory. |
| 225 var script = path.normalize(path.absolute(entrypoints[0].toNativePath())); |
| 226 var dir = path.join(path.dirname(script), 'packages/'); |
| 227 if (new Directory(dir).existsSync()) { |
| 228 // TODO(amouravski): convert all of dartdoc to use pathos. |
| 229 packageRoot = new Path(dir); |
| 230 } else { |
| 231 // If there is not, then check if the entrypoint is somewhere in a `lib` |
| 232 // directory. |
| 233 dir = path.dirname(script); |
| 234 var parts = path.split(dir); |
| 235 var libDir = parts.lastIndexOf('lib'); |
| 236 if (libDir > 0) { |
| 237 packageRoot = new Path(path.join(path.joinAll(parts.take(libDir)), |
| 238 'packages')); |
| 239 } |
| 240 } |
| 241 } |
227 | 242 |
228 cleanOutputDirectory(dartdoc.outputDir); | 243 cleanOutputDirectory(dartdoc.outputDir); |
229 | 244 |
230 // Start the analysis and documentation. | 245 // Start the analysis and documentation. |
231 dartdoc.documentLibraries(entrypoints, libPath, packageRoot) | 246 dartdoc.documentLibraries(entrypoints, libPath, packageRoot) |
232 .then((_) { | 247 .then((_) { |
233 print('Copying static files...'); | 248 print('Copying static files...'); |
234 Future.wait([ | 249 Future.wait([ |
235 // Prepare the dart2js script code and copy static resources. | 250 // Prepare the dart2js script code and copy static resources. |
236 // TODO(amouravski): move compileScript out and pre-generate the client | 251 // TODO(amouravski): move compileScript out and pre-generate the client |
237 // scripts. This takes a long time and the js hardly ever changes. | 252 // scripts. This takes a long time and the js hardly ever changes. |
238 compileScript(dartdoc.mode, dartdoc.outputDir, libPath), | 253 compileScript(dartdoc.mode, dartdoc.outputDir, libPath), |
239 copyDirectory(scriptDir.append('../static'), dartdoc.outputDir) | 254 copyDirectory(scriptDir.append('../static'), dartdoc.outputDir) |
240 ]); | 255 ]); |
241 }) | 256 }) |
242 .then((_) { | 257 .then((_) { |
243 print(dartdoc.status); | 258 print(dartdoc.status); |
244 if (dartdoc.totals == 0) { | 259 if (dartdoc.totals == 0) { |
245 exit(1); | 260 exit(1); |
246 } | 261 } |
247 }) | 262 }) |
248 .catchError((e) { | 263 .catchError((e) { |
249 print('Error: generation failed: ${e}'); | 264 print('Error: generation failed: ${e}'); |
250 dartdoc.cleanup(); | 265 dartdoc.cleanup(); |
251 exit(1); | 266 exit(1); |
252 }) | 267 }) |
253 .whenComplete(() => dartdoc.cleanup()); | 268 .whenComplete(() => dartdoc.cleanup()); |
254 } | 269 } |
255 | |
256 String _getPackageRoot(List<Uri> entrypoints) { | |
257 // Check if there's a `packages` directory in the entry point directory. | |
258 var fileEntrypoint = entrypoints.firstWhere( | |
259 (entrypoint) => entrypoint.scheme == 'file', | |
260 orElse: () => null); | |
261 if (fileEntrypoint == null) return; | |
262 | |
263 var script = path.normalize(path.absolute(fileUriToPath(fileEntrypoint))); | |
264 var dir = path.join(path.dirname(script), 'packages/'); | |
265 if (new Directory(dir).existsSync()) return dir; | |
266 | |
267 // If there is not, then check if the entrypoint is somewhere in a `lib` | |
268 // directory. | |
269 var parts = path.split(path.dirname(script)); | |
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 |