sdk/lib/_internal/dartdoc/bin/dartdoc.dart - sdk.git - Git at Google

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.

 /**
  * To generate docs for a library, run this script with the path to an
  * entrypoint .dart file, like:
  *
  *     $ dart dartdoc.dart foo.dart
  *
  * This will create a "docs" directory with the docs for your libraries. To
  * create these beautiful docs, dartdoc parses your library and every library
  * it imports (recursively). From each library, it parses all classes and
  * members, finds the associated doc comments and builds crosslinked docs from
  * them.
  */
 library dartdoc;

 import 'dart:async';
 import 'dart:io';

 // TODO(rnystrom): Use "package:" URL (#4968).
 import '../lib/dartdoc.dart';
 import '../lib/src/dartdoc/utils.dart';
 import 'package:args/args.dart';
 import 'package:pathos/path.dart' as path;

 /**
  * Run this from the `lib/_internal/dartdoc` directory.
  */
 main() {
   mainWithOptions(new Options());
 }

 /**
  * We use this to include dartdoc in a single snapshot with dart2js.
  * (They share 90% of the code)
  */
 mainWithOptions(Options options) {
   // Need this because ArgParser.getUsage doesn't show command invocation.
   final USAGE = 'Usage dartdoc [options] <entrypoint(s)>\n[options] include:';

   final args = options.arguments;

   final dartdoc = new Dartdoc();

   final argParser = new ArgParser();

   Path libPath = scriptDir.append('../../../../');

   String packageRoot;

   argParser.addFlag('no-code',
       help: 'Do not include source code in the documentation.',
       defaultsTo: false, negatable: false,
       callback: (noCode) => dartdoc.includeSource = !noCode);

   argParser.addOption('mode', abbr: 'm',
       help: 'Define how HTML pages are generated.',
       allowed: ['static', 'live-nav'], allowedHelp: {
         'static': 'Generates completely static HTML containing\n'
           'everything you need to browse the docs. The only\n'
           'client side behavior is trivial stuff like syntax\n'
           'highlighting code, and the find-as-you-type search\n'
           'box.',
         'live-nav': '(Default) Generated docs do not included baked HTML\n'
           'navigation. Instead a single `nav.json` file is\n'
           'created and the appropriate navigation is generated\n'
           'client-side by parsing that and building HTML.\n'
           '\tThis dramatically reduces the generated size of\n'
           'the HTML since a large fraction of each static page\n'
           'is just redundant navigation links.\n'
           '\tIn this mode, the browser will do a XHR for\n'
           'nav.json which means that to preview docs locallly,\n'
           'you will need to enable requesting file:// links in\n'
           'your browser or run a little local server like\n'
           '`python -m  SimpleHTTPServer`.'},
         defaultsTo: 'live-nav',
         callback: (genMode) {
           dartdoc.mode = (genMode == 'static' ? MODE_STATIC : MODE_LIVE_NAV);
         });

   argParser.addFlag('generate-app-cache',
       help: 'Generates the App Cache manifest file, enabling\n'
         'offline doc viewing.',
         defaultsTo: false, negatable: false,
         callback: (generate) => dartdoc.generateAppCache = generate);

   argParser.addFlag('omit-generation-time',
       help: 'Omits generation timestamp from output.',
       defaultsTo: false, negatable: false,
       callback: (genTimestamp) => dartdoc.omitGenerationTime = genTimestamp);

   argParser.addFlag('verbose', abbr: 'v',
       help: 'Print verbose information during generation.',
       defaultsTo: false, negatable: false,
       callback: (verb) => dartdoc.verbose = verb);

   argParser.addFlag('include-api',
       help: 'Include the used API libraries in the generated\n'
         'documentation. If the --link-api option is used,\n'
         'this option is ignored.',
       defaultsTo: false, negatable: false,
       callback: (incApi) => dartdoc.includeApi = incApi);

   argParser.addFlag('link-api',
       help: 'Link to the online language API in the generated\n'
         'documentation. The option overrides inclusion\n'
         'through --include-api or --include-lib.',
       defaultsTo: false, negatable: false,
       callback: (linkApi) => dartdoc.linkToApi = linkApi);

   argParser.addFlag('show-private',
       help: 'Document private types and members.',
       defaultsTo: false,
       callback: (showPrivate) => dartdoc.showPrivate = showPrivate);

   argParser.addFlag('inherit-from-object',
       help: 'Show members inherited from Object.',
       defaultsTo: false, negatable: false,
       callback: (inherit) => dartdoc.inheritFromObject = inherit);

   argParser.addFlag('enable-diagnostic-colors', negatable: false);

   argParser.addOption('out',
       help: 'Generates files into directory specified. If\n'
         'omitted the files are generated into ./docs/',
       callback: (outDir) {
         if(outDir != null) {
           dartdoc.outputDir = new Path(outDir);
         }
       });

   argParser.addOption('include-lib',
       help: 'Use this option to explicitly specify which\n'
         'libraries to include in the documentation. If\n'
         'omitted, all used libraries are included by\n'
         'default. Specify a comma-separated list of\n'
         'library names, or call this option multiple times.',
       callback: (incLibs) {
         if(!incLibs.isEmpty) {
           List<String> allLibs = new List<String>();
           for(final lst in incLibs) {
             var someLibs = lst.split(',');
             for(final lib in someLibs) {
               allLibs.add(lib);
             }
           }
           dartdoc.includedLibraries = allLibs;
         }
       }, allowMultiple: true);

   argParser.addOption('exclude-lib',
       help: 'Use this option to explicitly specify which\n'
         'libraries to exclude from the documentation. If\n'
         'omitted, no libraries are excluded. Specify a\n'
         'comma-separated list of library names, or call\n'
         'this option multiple times.',
       callback: (excLibs) {
         if(!excLibs.isEmpty) {
           List<String> allLibs = new List<String>();
           for(final lst in excLibs) {
             var someLibs = lst.split(',');
             for(final lib in someLibs) {
               allLibs.add(lib);
             }
           }
           dartdoc.excludedLibraries = allLibs;
         }
       }, allowMultiple: true);

   argParser.addOption('package-root',
       help: 'Sets the package directory to the specified directory.\n'
         'If omitted the package directory is the closest packages directory to'
         ' the entrypoint.',
       callback: (packageDir) {
         if(packageDir != null) {
           packageRoot = packageDir;
         }
       });

   argParser.addOption('library-root',
       help: 'Sets the library root directory to the specified directory.',
       callback: (libraryRoot) {
         if (libraryRoot != null) {
           libPath = new Path(libraryRoot);
         }
       });

   // TODO(amouravski): This method is deprecated. Remove on April 22.
   argParser.addOption('pkg',
       help: 'Deprecated: same as --package-root.',
       callback: (packageDir) {
         if(packageDir != null) {
           packageRoot = packageDir;
         }
       });

   dartdoc.dartdocPath = libPath.append('lib/_internal/dartdoc');

   if (args.isEmpty) {
     print('No arguments provided.');
     print(USAGE);
     print(argParser.getUsage());
     exit(1);
   }

   final entrypoints = <Uri>[];
   try {
     final option = argParser.parse(args);

     // This checks to see if the root of all entrypoints is the same.
     // If it is not, then we display a warning, as package imports might fail.
     var entrypointRoot;
     for (final entrypoint in option.rest) {
       var uri = Uri.parse(entrypoint);
       if (uri.scheme == '') uri = pathToFileUri(entrypoint);
       entrypoints.add(uri);

       if (uri.scheme != 'file') continue;
       if (entrypointRoot == null) {
         entrypointRoot = path.dirname(entrypoint);
       } else if (entrypointRoot != path.dirname(entrypoint)) {
         print('Warning: entrypoints are at different directories. "package:"'
             ' imports may fail.');
       }
     }
   } on FormatException catch (e) {
     print(e.message);
     print(USAGE);
     print(argParser.getUsage());
     exit(1);
   }

   if (entrypoints.isEmpty) {
     print('No entrypoints provided.');
     print(argParser.getUsage());
     exit(1);
   }

   if (packageRoot == null) packageRoot = _getPackageRoot(entrypoints);

   cleanOutputDirectory(dartdoc.outputDir);

   // Start the analysis and documentation.
   dartdoc.documentLibraries(entrypoints, libPath, packageRoot)
     // Prepare the dart2js script code and copy static resources.
     // TODO(amouravski): move compileScript out and pre-generate the client
     // scripts. This takes a long time and the js hardly ever changes.
     .then((_) => compileScript(dartdoc.mode, dartdoc.outputDir, libPath,
           dartdoc.tmpPath))
     .then((_) => copyDirectory(libPath.append('lib/_internal/dartdoc/static'),
                                dartdoc.outputDir))
     .then((_) {
       print(dartdoc.status);
       if (dartdoc.totals == 0) {
         exit(1);
       }
     })
     .catchError((e) {
       print('Error: generation failed: ${e}');
       var trace = getAttachedStackTrace(e);
       if (trace != null) print("StackTrace: $trace");
       dartdoc.cleanup();
       exit(1);
     })
     .whenComplete(() => dartdoc.cleanup());
 }

 String _getPackageRoot(List<Uri> entrypoints) {
   // Check if there's a `packages` directory in the entry point directory.
   var fileEntrypoint = entrypoints.firstWhere(
       (entrypoint) => entrypoint.scheme == 'file',
       orElse: () => null);
   if (fileEntrypoint == null) return;

   var script = path.normalize(path.absolute(fileUriToPath(fileEntrypoint)));
   var dir = path.join(path.dirname(script), 'packages/');
   if (new Directory(dir).existsSync()) return dir;

   // If there is not, then check if the entrypoint is somewhere in a `lib`
   // directory.
   var parts = path.split(path.dirname(script));
   var libDir = parts.lastIndexOf('lib');
   if (libDir > 0) {
     return path.join(path.joinAll(parts.take(libDir)), 'packages');
   } else {
     return null;
   }
 }
	// Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file
	// for details. All rights reserved. Use of this source code is governed by a
	// BSD-style license that can be found in the LICENSE file.

	/**
	* To generate docs for a library, run this script with the path to an
	* entrypoint .dart file, like:
	*
	* $ dart dartdoc.dart foo.dart
	*
	* This will create a "docs" directory with the docs for your libraries. To
	* create these beautiful docs, dartdoc parses your library and every library
	* it imports (recursively). From each library, it parses all classes and
	* members, finds the associated doc comments and builds crosslinked docs from
	* them.
	*/
	library dartdoc;

	import 'dart:async';
	import 'dart:io';

	// TODO(rnystrom): Use "package:" URL (#4968).
	import '../lib/dartdoc.dart';
	import '../lib/src/dartdoc/utils.dart';
	import 'package:args/args.dart';
	import 'package:pathos/path.dart' as path;

	/**
	* Run this from the `lib/_internal/dartdoc` directory.
	*/
	main() {
	mainWithOptions(new Options());
	}

	/**
	* We use this to include dartdoc in a single snapshot with dart2js.
	* (They share 90% of the code)
	*/
	mainWithOptions(Options options) {
	// Need this because ArgParser.getUsage doesn't show command invocation.
	final USAGE = 'Usage dartdoc [options] <entrypoint(s)>\n[options] include:';

	final args = options.arguments;

	final dartdoc = new Dartdoc();

	final argParser = new ArgParser();

	Path libPath = scriptDir.append('../../../../');

	String packageRoot;

	argParser.addFlag('no-code',
	help: 'Do not include source code in the documentation.',
	defaultsTo: false, negatable: false,
	callback: (noCode) => dartdoc.includeSource = !noCode);

	argParser.addOption('mode', abbr: 'm',
	help: 'Define how HTML pages are generated.',
	allowed: ['static', 'live-nav'], allowedHelp: {
	'static': 'Generates completely static HTML containing\n'
	'everything you need to browse the docs. The only\n'
	'client side behavior is trivial stuff like syntax\n'
	'highlighting code, and the find-as-you-type search\n'
	'box.',
	'live-nav': '(Default) Generated docs do not included baked HTML\n'
	'navigation. Instead a single `nav.json` file is\n'
	'created and the appropriate navigation is generated\n'
	'client-side by parsing that and building HTML.\n'
	'\tThis dramatically reduces the generated size of\n'
	'the HTML since a large fraction of each static page\n'
	'is just redundant navigation links.\n'
	'\tIn this mode, the browser will do a XHR for\n'
	'nav.json which means that to preview docs locallly,\n'
	'you will need to enable requesting file:// links in\n'
	'your browser or run a little local server like\n'
	'`python -m SimpleHTTPServer`.'},
	defaultsTo: 'live-nav',
	callback: (genMode) {
	dartdoc.mode = (genMode == 'static' ? MODE_STATIC : MODE_LIVE_NAV);
	});

	argParser.addFlag('generate-app-cache',
	help: 'Generates the App Cache manifest file, enabling\n'
	'offline doc viewing.',
	defaultsTo: false, negatable: false,
	callback: (generate) => dartdoc.generateAppCache = generate);

	argParser.addFlag('omit-generation-time',
	help: 'Omits generation timestamp from output.',
	defaultsTo: false, negatable: false,
	callback: (genTimestamp) => dartdoc.omitGenerationTime = genTimestamp);

	argParser.addFlag('verbose', abbr: 'v',
	help: 'Print verbose information during generation.',
	defaultsTo: false, negatable: false,
	callback: (verb) => dartdoc.verbose = verb);

	argParser.addFlag('include-api',
	help: 'Include the used API libraries in the generated\n'
	'documentation. If the --link-api option is used,\n'
	'this option is ignored.',
	defaultsTo: false, negatable: false,
	callback: (incApi) => dartdoc.includeApi = incApi);

	argParser.addFlag('link-api',
	help: 'Link to the online language API in the generated\n'
	'documentation. The option overrides inclusion\n'
	'through --include-api or --include-lib.',
	defaultsTo: false, negatable: false,
	callback: (linkApi) => dartdoc.linkToApi = linkApi);

	argParser.addFlag('show-private',
	help: 'Document private types and members.',
	defaultsTo: false,
	callback: (showPrivate) => dartdoc.showPrivate = showPrivate);

	argParser.addFlag('inherit-from-object',
	help: 'Show members inherited from Object.',
	defaultsTo: false, negatable: false,
	callback: (inherit) => dartdoc.inheritFromObject = inherit);

	argParser.addFlag('enable-diagnostic-colors', negatable: false);

	argParser.addOption('out',
	help: 'Generates files into directory specified. If\n'
	'omitted the files are generated into ./docs/',
	callback: (outDir) {
	if(outDir != null) {
	dartdoc.outputDir = new Path(outDir);
	}
	});

	argParser.addOption('include-lib',
	help: 'Use this option to explicitly specify which\n'
	'libraries to include in the documentation. If\n'
	'omitted, all used libraries are included by\n'
	'default. Specify a comma-separated list of\n'
	'library names, or call this option multiple times.',
	callback: (incLibs) {
	if(!incLibs.isEmpty) {
	List<String> allLibs = new List<String>();
	for(final lst in incLibs) {
	var someLibs = lst.split(',');
	for(final lib in someLibs) {
	allLibs.add(lib);
	}
	}
	dartdoc.includedLibraries = allLibs;
	}
	}, allowMultiple: true);

	argParser.addOption('exclude-lib',
	help: 'Use this option to explicitly specify which\n'
	'libraries to exclude from the documentation. If\n'
	'omitted, no libraries are excluded. Specify a\n'
	'comma-separated list of library names, or call\n'
	'this option multiple times.',
	callback: (excLibs) {
	if(!excLibs.isEmpty) {
	List<String> allLibs = new List<String>();
	for(final lst in excLibs) {
	var someLibs = lst.split(',');
	for(final lib in someLibs) {
	allLibs.add(lib);
	}
	}
	dartdoc.excludedLibraries = allLibs;
	}
	}, allowMultiple: true);

	argParser.addOption('package-root',
	help: 'Sets the package directory to the specified directory.\n'
	'If omitted the package directory is the closest packages directory to'
	' the entrypoint.',
	callback: (packageDir) {
	if(packageDir != null) {
	packageRoot = packageDir;
	}
	});

	argParser.addOption('library-root',
	help: 'Sets the library root directory to the specified directory.',
	callback: (libraryRoot) {
	if (libraryRoot != null) {
	libPath = new Path(libraryRoot);
	}
	});

	// TODO(amouravski): This method is deprecated. Remove on April 22.
	argParser.addOption('pkg',
	help: 'Deprecated: same as --package-root.',
	callback: (packageDir) {
	if(packageDir != null) {
	packageRoot = packageDir;
	}
	});

	dartdoc.dartdocPath = libPath.append('lib/_internal/dartdoc');

	if (args.isEmpty) {
	print('No arguments provided.');
	print(USAGE);
	print(argParser.getUsage());
	exit(1);
	}

	final entrypoints = <Uri>[];
	try {
	final option = argParser.parse(args);

	// This checks to see if the root of all entrypoints is the same.
	// If it is not, then we display a warning, as package imports might fail.
	var entrypointRoot;
	for (final entrypoint in option.rest) {
	var uri = Uri.parse(entrypoint);
	if (uri.scheme == '') uri = pathToFileUri(entrypoint);
	entrypoints.add(uri);

	if (uri.scheme != 'file') continue;
	if (entrypointRoot == null) {
	entrypointRoot = path.dirname(entrypoint);
	} else if (entrypointRoot != path.dirname(entrypoint)) {
	print('Warning: entrypoints are at different directories. "package:"'
	' imports may fail.');
	}
	}
	} on FormatException catch (e) {
	print(e.message);
	print(USAGE);
	print(argParser.getUsage());
	exit(1);
	}

	if (entrypoints.isEmpty) {
	print('No entrypoints provided.');
	print(argParser.getUsage());
	exit(1);
	}

	if (packageRoot == null) packageRoot = _getPackageRoot(entrypoints);

	cleanOutputDirectory(dartdoc.outputDir);

	// Start the analysis and documentation.
	dartdoc.documentLibraries(entrypoints, libPath, packageRoot)
	// Prepare the dart2js script code and copy static resources.
	// TODO(amouravski): move compileScript out and pre-generate the client
	// scripts. This takes a long time and the js hardly ever changes.
	.then((_) => compileScript(dartdoc.mode, dartdoc.outputDir, libPath,
	dartdoc.tmpPath))
	.then((_) => copyDirectory(libPath.append('lib/_internal/dartdoc/static'),
	dartdoc.outputDir))
	.then((_) {
	print(dartdoc.status);
	if (dartdoc.totals == 0) {
	exit(1);
	}
	})
	.catchError((e) {
	print('Error: generation failed: ${e}');
	var trace = getAttachedStackTrace(e);
	if (trace != null) print("StackTrace: $trace");
	dartdoc.cleanup();
	exit(1);
	})
	.whenComplete(() => dartdoc.cleanup());
	}

	String _getPackageRoot(List<Uri> entrypoints) {
	// Check if there's a `packages` directory in the entry point directory.
	var fileEntrypoint = entrypoints.firstWhere(
	(entrypoint) => entrypoint.scheme == 'file',
	orElse: () => null);
	if (fileEntrypoint == null) return;

	var script = path.normalize(path.absolute(fileUriToPath(fileEntrypoint)));
	var dir = path.join(path.dirname(script), 'packages/');
	if (new Directory(dir).existsSync()) return dir;

	// If there is not, then check if the entrypoint is somewhere in a `lib`
	// directory.
	var parts = path.split(path.dirname(script));
	var libDir = parts.lastIndexOf('lib');
	if (libDir > 0) {
	return path.join(path.joinAll(parts.take(libDir)), 'packages');
	} else {
	return null;
	}
	}