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 |