| OLD | NEW |
| 1 // Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2013, 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 /// **docgen** is a tool for creating machine readable representations of Dart | 5 /// **docgen** is a tool for creating machine readable representations of Dart |
| 6 /// code metadata, including: classes, members, comments and annotations. | 6 /// code metadata, including: classes, members, comments and annotations. |
| 7 /// | 7 /// |
| 8 /// docgen is run on a `.dart` file or a directory containing `.dart` files. | 8 /// docgen is run on a `.dart` file or a directory containing `.dart` files. |
| 9 /// | 9 /// |
| 10 /// $ dart docgen.dart [OPTIONS] [FILE/DIR] | 10 /// $ dart docgen.dart [OPTIONS] [FILE/DIR] |
| (...skipping 97 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 108 /// This option is useful when only the SDK libraries are needed. | 108 /// This option is useful when only the SDK libraries are needed. |
| 109 /// If [serve] is `true`, then after generating the documents we fire up a | 109 /// If [serve] is `true`, then after generating the documents we fire up a |
| 110 /// simple server to view the documentation. | 110 /// simple server to view the documentation. |
| 111 /// | 111 /// |
| 112 /// Returned Future completes with true if document generation is successful. | 112 /// Returned Future completes with true if document generation is successful. |
| 113 Future<bool> docgen(List<String> files, {String packageRoot, | 113 Future<bool> docgen(List<String> files, {String packageRoot, |
| 114 bool outputToYaml: true, bool includePrivate: false, bool includeSdk: false, | 114 bool outputToYaml: true, bool includePrivate: false, bool includeSdk: false, |
| 115 bool parseSdk: false, bool append: false, String introFileName: '', | 115 bool parseSdk: false, bool append: false, String introFileName: '', |
| 116 out: _DEFAULT_OUTPUT_DIRECTORY, List<String> excludeLibraries : const [], | 116 out: _DEFAULT_OUTPUT_DIRECTORY, List<String> excludeLibraries : const [], |
| 117 bool includeDependentPackages: false, bool serve: false, | 117 bool includeDependentPackages: false, bool serve: false, |
| 118 bool noDocs: false, String startPage}) { | 118 bool noDocs: false, String startPage, |
| 119 String pubScript, String dartBinary}) { |
| 119 var result; | 120 var result; |
| 120 if (!noDocs) { | 121 if (!noDocs) { |
| 121 _Viewer.ensureMovedViewerCode(); | 122 _Viewer.ensureMovedViewerCode(); |
| 122 result = _Generator.generateDocumentation(files, packageRoot: packageRoot, | 123 result = _Generator.generateDocumentation(files, packageRoot: packageRoot, |
| 123 outputToYaml: outputToYaml, includePrivate: includePrivate, | 124 outputToYaml: outputToYaml, includePrivate: includePrivate, |
| 124 includeSdk: includeSdk, parseSdk: parseSdk, append: append, | 125 includeSdk: includeSdk, parseSdk: parseSdk, append: append, |
| 125 introFileName: introFileName, out: out, | 126 introFileName: introFileName, out: out, |
| 126 excludeLibraries: excludeLibraries, | 127 excludeLibraries: excludeLibraries, |
| 127 includeDependentPackages: includeDependentPackages, | 128 includeDependentPackages: includeDependentPackages, |
| 128 startPage: startPage); | 129 startPage: startPage, pubScript: pubScript, dartBinary: dartBinary); |
| 129 _Viewer.addBackViewerCode(); | 130 _Viewer.addBackViewerCode(); |
| 130 if (serve) { | 131 if (serve) { |
| 131 result.then((success) { | 132 result.then((success) { |
| 132 if (success) { | 133 if (success) { |
| 133 _Viewer._cloneAndServe(); | 134 _Viewer._cloneAndServe(); |
| 134 } | 135 } |
| 135 }); | 136 }); |
| 136 } | 137 } |
| 137 } else if (serve) { | 138 } else if (serve) { |
| 138 _Viewer._cloneAndServe(); | 139 _Viewer._cloneAndServe(); |
| (...skipping 101 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 240 | 241 |
| 241 /// This is set from the command line arguments flag --include-private | 242 /// This is set from the command line arguments flag --include-private |
| 242 static bool _includePrivate = false; | 243 static bool _includePrivate = false; |
| 243 | 244 |
| 244 /// Library names to explicitly exclude. | 245 /// Library names to explicitly exclude. |
| 245 /// | 246 /// |
| 246 /// Set from the command line option | 247 /// Set from the command line option |
| 247 /// --exclude-lib. | 248 /// --exclude-lib. |
| 248 static List<String> _excluded; | 249 static List<String> _excluded; |
| 249 | 250 |
| 251 /// The path of the pub script. |
| 252 static String _pubScript; |
| 253 |
| 254 /// The path of Dart binary. |
| 255 static String _dartBinary; |
| 256 |
| 250 /// Logger for printing out progress of documentation generation. | 257 /// Logger for printing out progress of documentation generation. |
| 251 static Logger logger = new Logger('Docgen'); | 258 static Logger logger = new Logger('Docgen'); |
| 252 | 259 |
| 253 /// Docgen constructor initializes the link resolver for markdown parsing. | 260 /// Docgen constructor initializes the link resolver for markdown parsing. |
| 254 /// Also initializes the command line arguments. | 261 /// Also initializes the command line arguments. |
| 255 /// | 262 /// |
| 256 /// [packageRoot] is the packages directory of the directory being analyzed. | 263 /// [packageRoot] is the packages directory of the directory being analyzed. |
| 257 /// If [includeSdk] is `true`, then any SDK libraries explicitly imported will | 264 /// If [includeSdk] is `true`, then any SDK libraries explicitly imported will |
| 258 /// also be documented. | 265 /// also be documented. |
| 259 /// If [parseSdk] is `true`, then all Dart SDK libraries will be documented. | 266 /// If [parseSdk] is `true`, then all Dart SDK libraries will be documented. |
| 260 /// This option is useful when only the SDK libraries are needed. | 267 /// This option is useful when only the SDK libraries are needed. |
| 261 /// | 268 /// |
| 262 /// Returned Future completes with true if document generation is successful. | 269 /// Returned Future completes with true if document generation is successful. |
| 263 static Future<bool> generateDocumentation(List<String> files, | 270 static Future<bool> generateDocumentation(List<String> files, |
| 264 {String packageRoot, bool outputToYaml: true, bool includePrivate: false, | 271 {String packageRoot, bool outputToYaml: true, bool includePrivate: false, |
| 265 bool includeSdk: false, bool parseSdk: false, bool append: false, | 272 bool includeSdk: false, bool parseSdk: false, bool append: false, |
| 266 String introFileName: '', out: _DEFAULT_OUTPUT_DIRECTORY, | 273 String introFileName: '', out: _DEFAULT_OUTPUT_DIRECTORY, |
| 267 List<String> excludeLibraries : const [], | 274 List<String> excludeLibraries : const [], |
| 268 bool includeDependentPackages: false, String startPage}) { | 275 bool includeDependentPackages: false, String startPage, |
| 276 String dartBinary, String pubScript}) { |
| 269 _excluded = excludeLibraries; | 277 _excluded = excludeLibraries; |
| 270 _includePrivate = includePrivate; | 278 _includePrivate = includePrivate; |
| 279 _pubScript = pubScript; |
| 280 _dartBinary = dartBinary; |
| 281 |
| 271 logger.onRecord.listen((record) => print(record.message)); | 282 logger.onRecord.listen((record) => print(record.message)); |
| 272 | 283 |
| 273 _ensureOutputDirectory(out, append); | 284 _ensureOutputDirectory(out, append); |
| 274 var updatedPackageRoot = _obtainPackageRoot(packageRoot, parseSdk, files); | 285 var updatedPackageRoot = _obtainPackageRoot(packageRoot, parseSdk, files); |
| 275 | 286 |
| 276 var requestedLibraries = _findLibrariesToDocument(files, | 287 var requestedLibraries = _findLibrariesToDocument(files, |
| 277 includeDependentPackages); | 288 includeDependentPackages); |
| 278 | 289 |
| 279 var allLibraries = []..addAll(requestedLibraries); | 290 var allLibraries = []..addAll(requestedLibraries); |
| 280 if (includeSdk) { | 291 if (includeSdk) { |
| (...skipping 307 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 588 } | 599 } |
| 589 }); | 600 }); |
| 590 return libraries; | 601 return libraries; |
| 591 } | 602 } |
| 592 | 603 |
| 593 /// All of the directories for our dependent packages | 604 /// All of the directories for our dependent packages |
| 594 /// If this is not a package, return an empty list. | 605 /// If this is not a package, return an empty list. |
| 595 static List<String> _allDependentPackageDirs(String packageDirectory) { | 606 static List<String> _allDependentPackageDirs(String packageDirectory) { |
| 596 var packageName = Library.packageNameFor(packageDirectory); | 607 var packageName = Library.packageNameFor(packageDirectory); |
| 597 if (packageName == '') return []; | 608 if (packageName == '') return []; |
| 598 var dependentsJson = Process.runSync('pub', ['list-package-dirs'], | 609 var dependentsJson = Process.runSync(_pubScript, ['list-package-dirs'], |
| 599 workingDirectory: packageDirectory, runInShell: true); | 610 workingDirectory: packageDirectory, runInShell: true); |
| 600 if (dependentsJson.exitCode != 0) { | 611 if (dependentsJson.exitCode != 0) { |
| 601 print(dependentsJson.stderr); | 612 print(dependentsJson.stderr); |
| 602 } | 613 } |
| 603 var dependents = JSON.decode(dependentsJson.stdout)['packages']; | 614 var dependents = JSON.decode(dependentsJson.stdout)['packages']; |
| 604 return dependents.values.toList(); | 615 return dependents.values.toList(); |
| 605 } | 616 } |
| 606 | 617 |
| 607 /// For all the libraries, return a list of the libraries that are part of | 618 /// For all the libraries, return a list of the libraries that are part of |
| 608 /// the SDK. | 619 /// the SDK. |
| (...skipping 67 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 676 print('Error cloning git repository:'); | 687 print('Error cloning git repository:'); |
| 677 print('process output: ${processResult.stdout}'); | 688 print('process output: ${processResult.stdout}'); |
| 678 print('process stderr: ${processResult.stderr}'); | 689 print('process stderr: ${processResult.stderr}'); |
| 679 } | 690 } |
| 680 } | 691 } |
| 681 } | 692 } |
| 682 | 693 |
| 683 /// Move the generated json/yaml docs directory to the dartdoc-viewer | 694 /// Move the generated json/yaml docs directory to the dartdoc-viewer |
| 684 /// directory, to run as a webpage. | 695 /// directory, to run as a webpage. |
| 685 static void _moveDirectoryAndServe() { | 696 static void _moveDirectoryAndServe() { |
| 686 var processResult = Process.runSync('pub', ['update'], runInShell: true, | 697 var processResult = Process.runSync(_Generator._pubScript, ['upgrade'], |
| 687 workingDirectory: path.join(_dartdocViewerDir.path, 'client')); | 698 runInShell: true, workingDirectory: path.join(_dartdocViewerDir.path, |
| 699 'client')); |
| 688 print('process output: ${processResult.stdout}'); | 700 print('process output: ${processResult.stdout}'); |
| 689 print('process stderr: ${processResult.stderr}'); | 701 print('process stderr: ${processResult.stderr}'); |
| 690 | 702 |
| 691 var dir = new Directory(_Generator._outputDirectory == null? 'docs' : | 703 var dir = new Directory(_Generator._outputDirectory == null? 'docs' : |
| 692 _Generator._outputDirectory); | 704 _Generator._outputDirectory); |
| 693 var webDocsDir = new Directory(path.join(_dartdocViewerDir.path, 'client', | 705 var webDocsDir = new Directory(path.join(_dartdocViewerDir.path, 'client', |
| 694 'web', 'docs')); | 706 'web', 'docs')); |
| 695 if (dir.existsSync()) { | 707 if (dir.existsSync()) { |
| 696 // Move the docs folder to dartdoc-viewer/client/web/docs | 708 // Move the docs folder to dartdoc-viewer/client/web/docs |
| 697 dir.renameSync(webDocsDir.path); | 709 dir.renameSync(webDocsDir.path); |
| 698 } | 710 } |
| 699 | 711 |
| 700 if (webDocsDir.existsSync()) { | 712 if (webDocsDir.existsSync()) { |
| 701 // Compile the code to JavaScript so we can run on any browser. | 713 // Compile the code to JavaScript so we can run on any browser. |
| 702 print('Compile app to JavaScript for viewing.'); | 714 print('Compile app to JavaScript for viewing.'); |
| 703 var processResult = Process.runSync('dart', ['deploy.dart'], | 715 var processResult = Process.runSync(_Generator._dartBinary, |
| 704 workingDirectory : path.join(_dartdocViewerDir.path, 'client'), | 716 ['deploy.dart'], workingDirectory : path.join(_dartdocViewerDir.path, |
| 705 runInShell: true); | 717 'client'), runInShell: true); |
| 706 print('process output: ${processResult.stdout}'); | 718 print('process output: ${processResult.stdout}'); |
| 707 print('process stderr: ${processResult.stderr}'); | 719 print('process stderr: ${processResult.stderr}'); |
| 708 _runServer(); | 720 _runServer(); |
| 709 } | 721 } |
| 710 } | 722 } |
| 711 | 723 |
| 712 /// A simple HTTP server. Implemented here because this is part of the SDK, | 724 /// A simple HTTP server. Implemented here because this is part of the SDK, |
| 713 /// so it shouldn't have any external dependencies. | 725 /// so it shouldn't have any external dependencies. |
| 714 static void _runServer() { | 726 static void _runServer() { |
| 715 // Launch a server to serve out of the directory dartdoc-viewer/client/web. | 727 // Launch a server to serve out of the directory dartdoc-viewer/client/web. |
| (...skipping 1458 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 2174 .map((e) => originalMirror.getField(e.simpleName).reflectee) | 2186 .map((e) => originalMirror.getField(e.simpleName).reflectee) |
| 2175 .where((e) => e != null) | 2187 .where((e) => e != null) |
| 2176 .toList(); | 2188 .toList(); |
| 2177 } | 2189 } |
| 2178 | 2190 |
| 2179 Map toMap() => { | 2191 Map toMap() => { |
| 2180 'name': Indexable.getDocgenObject(mirror, owningLibrary).docName, | 2192 'name': Indexable.getDocgenObject(mirror, owningLibrary).docName, |
| 2181 'parameters': parameters | 2193 'parameters': parameters |
| 2182 }; | 2194 }; |
| 2183 } | 2195 } |
| OLD | NEW |