| 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 use it, from this directory, run: | 6 * To generate docs for a library, run this script with the path to an |
| 7 * entrypoint .dart file, like: |
| 7 * | 8 * |
| 8 * $ ./dartdoc <path to .dart file> | 9 * $ dart dartdoc.dart foo.dart |
| 9 * | 10 * |
| 10 * 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 |
| 11 * create these beautiful docs, dartdoc parses your library and every library | 12 * create these beautiful docs, dartdoc parses your library and every library |
| 12 * it imports (recursively). From each library, it parses all classes and | 13 * it imports (recursively). From each library, it parses all classes and |
| 13 * members, finds the associated doc comments and builds crosslinked docs from | 14 * members, finds the associated doc comments and builds crosslinked docs from |
| 14 * them. | 15 * them. |
| 15 */ | 16 */ |
| 16 #library('dartdoc'); | 17 #library('dartdoc'); |
| 17 | 18 |
| 18 #import('dart:io'); | 19 #import('dart:io'); |
| (...skipping 63 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 82 return; | 83 return; |
| 83 } | 84 } |
| 84 break; | 85 break; |
| 85 } | 86 } |
| 86 } | 87 } |
| 87 | 88 |
| 88 // The entrypoint of the library to generate docs for. | 89 // The entrypoint of the library to generate docs for. |
| 89 final entrypoint = args[args.length - 1]; | 90 final entrypoint = args[args.length - 1]; |
| 90 | 91 |
| 91 final files = new VMFileSystem(); | 92 final files = new VMFileSystem(); |
| 92 // TODO(rnystrom): Note that the following line gets munged by create-sdk to | 93 |
| 93 // work with the SDK's different file layout. If you change it here, make | 94 // TODO(rnystrom): Note that the following lines get munged by create-sdk to |
| 94 // sure SDK builds still work. | 95 // work with the SDK's different file layout. If you change, be sure to test |
| 95 parseOptions('../../frog', ['', '', '--libdir=../../frog/lib'], files); | 96 // that dartdoc still works when run from the built SDK directory. |
| 97 final frogPath = joinPaths(scriptDir, '../../frog/'); |
| 98 final libDir = joinPaths(frogPath, 'lib'); |
| 99 final compilerPath = joinPaths(frogPath, 'minfrog'); |
| 100 |
| 101 parseOptions(frogPath, ['', '', '--libdir=$libDir'], files); |
| 96 initializeWorld(files); | 102 initializeWorld(files); |
| 97 | 103 |
| 98 var dartdoc; | 104 final dartdoc = new Dartdoc(); |
| 99 final elapsed = time(() { | |
| 100 dartdoc = new Dartdoc(); | |
| 101 | 105 |
| 102 if (includeSource != null) dartdoc.includeSource = includeSource; | 106 if (includeSource != null) dartdoc.includeSource = includeSource; |
| 103 if (mode != null) dartdoc.mode = mode; | 107 if (mode != null) dartdoc.mode = mode; |
| 104 if (outputDir != null) dartdoc.outputDir = outputDir; | 108 if (outputDir != null) dartdoc.outputDir = outputDir; |
| 105 | 109 |
| 106 cleanOutputDirectory(outputDir); | 110 cleanOutputDirectory(dartdoc.outputDir); |
| 107 | 111 |
| 108 // TODO(rnystrom): Use platform-specific path separator. | 112 // Compile the client-side code to JS. |
| 109 copyFiles('$scriptDir/static', outputDir); | 113 final clientScript = (dartdoc.mode == MODE_STATIC) ? 'static' : 'live-nav'; |
| 114 compileScript(compilerPath, libDir, '$scriptDir/client-$clientScript.dart', |
| 115 '${dartdoc.outputDir}/client-$clientScript.js'); |
| 110 | 116 |
| 111 dartdoc.document(entrypoint); | 117 copyFiles('$scriptDir/static', dartdoc.outputDir); |
| 112 }); | 118 |
| 119 dartdoc.document(entrypoint); |
| 113 | 120 |
| 114 print('Documented ${dartdoc._totalLibraries} libraries, ' + | 121 print('Documented ${dartdoc._totalLibraries} libraries, ' + |
| 115 '${dartdoc._totalTypes} types, and ' + | 122 '${dartdoc._totalTypes} types, and ' + |
| 116 '${dartdoc._totalMembers} members in ${elapsed}msec.'); | 123 '${dartdoc._totalMembers} members.'); |
| 117 } | 124 } |
| 118 | 125 |
| 119 /** | 126 /** |
| 120 * Gets the full path to the directory containing the entrypoint of the current | 127 * Gets the full path to the directory containing the entrypoint of the current |
| 121 * script. In other words, if you invoked dartdoc, directly, it will be the | 128 * script. In other words, if you invoked dartdoc, directly, it will be the |
| 122 * path to the directory containing `dartdoc.dart`. If you're running a script | 129 * path to the directory containing `dartdoc.dart`. If you're running a script |
| 123 * that imports dartdoc, it will be the path to that script. | 130 * that imports dartdoc, it will be the path to that script. |
| 124 */ | 131 */ |
| 125 String get scriptDir() { | 132 String get scriptDir() { |
| 126 return dirname(new File(new Options().script).fullPathSync()); | 133 return dirname(new File(new Options().script).fullPathSync()); |
| (...skipping 27 matching lines...) Expand all Loading... |
| 154 new File(path).readAsBytes((bytes) { | 161 new File(path).readAsBytes((bytes) { |
| 155 final outFile = new File('$to/$name'); | 162 final outFile = new File('$to/$name'); |
| 156 final stream = outFile.openOutputStream(FileMode.WRITE); | 163 final stream = outFile.openOutputStream(FileMode.WRITE); |
| 157 stream.write(bytes, copyBuffer: false); | 164 stream.write(bytes, copyBuffer: false); |
| 158 stream.close(); | 165 stream.close(); |
| 159 }); | 166 }); |
| 160 }; | 167 }; |
| 161 fromDir.list(recursive: false); | 168 fromDir.list(recursive: false); |
| 162 } | 169 } |
| 163 | 170 |
| 171 /** |
| 172 * Compiles the given Dart script to a JavaScript file at [jsPath] using the |
| 173 * Dart-to-JS compiler located at [compilerPath]. |
| 174 */ |
| 175 void compileScript(String compilerPath, String libDir, |
| 176 String dartPath, String jsPath) { |
| 177 final process = new Process.start(compilerPath, [ |
| 178 '--libdir=$libDir', '--out=$jsPath', |
| 179 '--compile-only', '--enable-type-checks', '--warnings-as-errors', |
| 180 dartPath]); |
| 181 |
| 182 process.stdout.pipe(stdout, close: false); |
| 183 |
| 184 process.onError = (error) { |
| 185 print('Failed to compile $dartPath. Error:'); |
| 186 print(error); |
| 187 }; |
| 188 } |
| 189 |
| 164 class Dartdoc { | 190 class Dartdoc { |
| 165 /** Set to `false` to not include the source code in the generated docs. */ | 191 /** Set to `false` to not include the source code in the generated docs. */ |
| 166 bool includeSource = true; | 192 bool includeSource = true; |
| 167 | 193 |
| 168 /** | 194 /** |
| 169 * Dartdoc can generate docs in a few different ways based on how dynamic you | 195 * Dartdoc can generate docs in a few different ways based on how dynamic you |
| 170 * want the client-side behavior to be. The value for this should be one of | 196 * want the client-side behavior to be. The value for this should be one of |
| 171 * the `MODE_` constants. | 197 * the `MODE_` constants. |
| 172 */ | 198 */ |
| 173 int mode = MODE_LIVE_NAV; | 199 int mode = MODE_LIVE_NAV; |
| (...skipping 59 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 233 // Patch in support for [:...:]-style code to the markdown parser. | 259 // Patch in support for [:...:]-style code to the markdown parser. |
| 234 // TODO(rnystrom): Markdown already has syntax for this. Phase this out? | 260 // TODO(rnystrom): Markdown already has syntax for this. Phase this out? |
| 235 md.InlineParser.syntaxes.insertRange(0, 1, | 261 md.InlineParser.syntaxes.insertRange(0, 1, |
| 236 new md.CodeSyntax(@'\[\:((?:.|\n)*?)\:\]')); | 262 new md.CodeSyntax(@'\[\:((?:.|\n)*?)\:\]')); |
| 237 | 263 |
| 238 md.setImplicitLinkResolver((name) => resolveNameReference(name, | 264 md.setImplicitLinkResolver((name) => resolveNameReference(name, |
| 239 library: _currentLibrary, type: _currentType, | 265 library: _currentLibrary, type: _currentType, |
| 240 member: _currentMember)); | 266 member: _currentMember)); |
| 241 } | 267 } |
| 242 | 268 |
| 243 void document(String entrypoint) { | 269 void document([String entrypoint]) { |
| 244 var oldDietParse = options.dietParse; | 270 var oldDietParse = options.dietParse; |
| 245 try { | 271 try { |
| 246 options.dietParse = true; | 272 options.dietParse = true; |
| 247 | 273 |
| 248 // Handle the built-in entrypoints. | 274 // If we have an entrypoint, process it. Otherwise, just use whatever |
| 249 switch (entrypoint) { | 275 // libraries have been previously loaded by the calling code. |
| 250 case 'corelib': | 276 if (entrypoint != null) { |
| 251 world.getOrAddLibrary('dart:core'); | 277 world.processDartScript(entrypoint); |
| 252 world.getOrAddLibrary('dart:coreimpl'); | |
| 253 world.getOrAddLibrary('dart:json'); | |
| 254 world.getOrAddLibrary('dart:isolate'); | |
| 255 world.process(); | |
| 256 break; | |
| 257 | |
| 258 case 'dom': | |
| 259 world.getOrAddLibrary('dart:core'); | |
| 260 world.getOrAddLibrary('dart:coreimpl'); | |
| 261 world.getOrAddLibrary('dart:json'); | |
| 262 world.getOrAddLibrary('dart:dom'); | |
| 263 world.getOrAddLibrary('dart:isolate'); | |
| 264 world.process(); | |
| 265 break; | |
| 266 | |
| 267 case 'html': | |
| 268 world.getOrAddLibrary('dart:core'); | |
| 269 world.getOrAddLibrary('dart:coreimpl'); | |
| 270 world.getOrAddLibrary('dart:json'); | |
| 271 world.getOrAddLibrary('dart:dom'); | |
| 272 world.getOrAddLibrary('dart:html'); | |
| 273 world.getOrAddLibrary('dart:isolate'); | |
| 274 world.process(); | |
| 275 break; | |
| 276 | |
| 277 default: | |
| 278 // Normal entrypoint script. | |
| 279 world.processDartScript(entrypoint); | |
| 280 } | 278 } |
| 281 | 279 |
| 282 world.resolveAll(); | 280 world.resolveAll(); |
| 283 | 281 |
| 284 // Sort the libraries by name (not key). | 282 // Sort the libraries by name (not key). |
| 285 _sortedLibraries = world.libraries.getValues(); | 283 _sortedLibraries = world.libraries.getValues(); |
| 286 _sortedLibraries.sort((a, b) { | 284 _sortedLibraries.sort((a, b) { |
| 287 return a.name.toUpperCase().compareTo(b.name.toUpperCase()); | 285 return a.name.toUpperCase().compareTo(b.name.toUpperCase()); |
| 288 }); | 286 }); |
| 289 | 287 |
| (...skipping 984 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 1274 | 1272 |
| 1275 return new md.Element.text('code', name); | 1273 return new md.Element.text('code', name); |
| 1276 } | 1274 } |
| 1277 | 1275 |
| 1278 // TODO(rnystrom): Move into SourceSpan? | 1276 // TODO(rnystrom): Move into SourceSpan? |
| 1279 int getSpanColumn(SourceSpan span) { | 1277 int getSpanColumn(SourceSpan span) { |
| 1280 final line = span.file.getLine(span.start); | 1278 final line = span.file.getLine(span.start); |
| 1281 return span.file.getColumn(line, span.start); | 1279 return span.file.getColumn(line, span.start); |
| 1282 } | 1280 } |
| 1283 } | 1281 } |
| OLD | NEW |