Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(458)

Side by Side Diff: sdk/lib/_internal/dartdoc/bin/dartdoc.dart

Issue 13986002: Revert dartdoc documenting exports. (Closed) Base URL: https://dart.googlecode.com/svn/branches/bleeding_edge/dart
Patch Set: Created 7 years, 8 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch | Annotate | Revision Log
« no previous file with comments | « no previous file | sdk/lib/_internal/dartdoc/lib/dartdoc.dart » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
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
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 }
OLDNEW
« no previous file with comments | « no previous file | sdk/lib/_internal/dartdoc/lib/dartdoc.dart » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698