Chromium Code Reviews Chromium Code Reviews
Issue 9019001:
Tweak dartdoc look to match dartlang.org a bit more. (Closed)
Base URL: https://dart.googlecode.com/svn/branches/bleeding_edge/dart| OLD | NEW |
|---|---|
| 1 // Copyright (c) 2011, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2011, 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 use it, from this directory, run: |
| 7 * | 7 * |
| 8 * $ ./dartdoc <path to .dart file> | 8 * $ ./dartdoc <path to .dart file> |
| 9 * | 9 * |
| 10 * This will create a "docs" directory with the docs for your libraries. To | 10 * This will create a "docs" directory with the docs for your libraries. To |
| (...skipping 49 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
| 60 | 60 |
| 61 print('Documented ${dartdoc._totalLibraries} libraries, ' + | 61 print('Documented ${dartdoc._totalLibraries} libraries, ' + |
| 62 '${dartdoc._totalTypes} types, and ' + | 62 '${dartdoc._totalTypes} types, and ' + |
| 63 '${dartdoc._totalMembers} members in ${elapsed}msec.'); | 63 '${dartdoc._totalMembers} members in ${elapsed}msec.'); |
| 64 } | 64 } |
| 65 | 65 |
| 66 class Dartdoc { | 66 class Dartdoc { |
| 67 /** Set to `false` to not include the source code in the generated docs. */ | 67 /** Set to `false` to not include the source code in the generated docs. */ |
| 68 bool includeSource = true; | 68 bool includeSource = true; |
| 69 | 69 |
| 70 /** | |
| 71 * The title used for the overall generated output. Set this to change it. | |
| 72 */ | |
| 73 String mainTitle = 'Dart Documentation'; | |
|
Emily Fortuna
2011/12/21 18:27:25
nit: Can we have a dart favicon like dartlang.org?
Bob Nystrom
2011/12/21 18:34:20
I tried to get that working for a little while but
| |
| 74 | |
| 70 CommentMap _comments; | 75 CommentMap _comments; |
| 71 | 76 |
| 72 /** The library that we're currently generating docs for. */ | 77 /** The library that we're currently generating docs for. */ |
| 73 Library _currentLibrary; | 78 Library _currentLibrary; |
| 74 | 79 |
| 75 /** The type that we're currently generating docs for. */ | 80 /** The type that we're currently generating docs for. */ |
| 76 Type _currentType; | 81 Type _currentType; |
| 77 | 82 |
| 78 /** The member that we're currently generating docs for. */ | 83 /** The member that we're currently generating docs for. */ |
| 79 Member _currentMember; | 84 Member _currentMember; |
| (...skipping 53 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
| 133 // Generate the docs. | 138 // Generate the docs. |
| 134 docIndex(); | 139 docIndex(); |
| 135 for (final library in world.libraries.getValues()) { | 140 for (final library in world.libraries.getValues()) { |
| 136 docLibrary(library); | 141 docLibrary(library); |
| 137 } | 142 } |
| 138 } finally { | 143 } finally { |
| 139 options.dietParse = oldDietParse; | 144 options.dietParse = oldDietParse; |
| 140 } | 145 } |
| 141 } | 146 } |
| 142 | 147 |
| 143 writeHeader(String title) { | 148 /** |
| 144 writeln( | 149 * Writes the page header with the given [title] and [breadcrumbs]. The |
| 150 * breadcrumbs are an interleaved list of links and titles. If a link is null, | |
| 151 * then no link will be generated. For example, given: | |
| 152 * | |
| 153 * ['foo', 'foo.html', 'bar', null] | |
| 154 * | |
| 155 * It will output: | |
| 156 * | |
| 157 * <a href="foo.html">foo</a> › bar | |
| 158 */ | |
| 159 writeHeader(String title, List<String> breadcrumbs) { | |
| 160 write( | |
| 145 ''' | 161 ''' |
| 146 <!DOCTYPE html> | 162 <!DOCTYPE html> |
| 147 <html> | 163 <html> |
| 148 <head> | 164 <head> |
| 149 <meta charset="utf-8"> | 165 <meta charset="utf-8"> |
| 150 <title>$title</title> | 166 <title>$title</title> |
| 151 <link rel="stylesheet" type="text/css" | 167 <link rel="stylesheet" type="text/css" |
| 152 href="${relativePath('styles.css')}" /> | 168 href="${relativePath('styles.css')}" /> |
| 153 <link href="http://fonts.googleapis.com/css?family=Open+Sans:400,600,700 ,800" rel="stylesheet" type="text/css"> | 169 <link href="http://fonts.googleapis.com/css?family=Open+Sans:400,600,700 ,800" rel="stylesheet" type="text/css"> |
| 154 <script src="${relativePath('interact.js')}"></script> | 170 <script src="${relativePath('interact.js')}"></script> |
| 155 </head> | 171 </head> |
| 156 <body> | 172 <body> |
| 157 <div class="page"> | 173 <div class="page"> |
| 174 <div class="header"> | |
| 175 ${a('index.html', '<div class="logo"></div>')} | |
| 176 ${a('index.html', mainTitle)} | |
| 158 '''); | 177 '''); |
| 178 | |
| 179 // Write the breadcrumb trail. | |
| 180 for (int i = 0; i < breadcrumbs.length; i += 2) { | |
| 181 if (breadcrumbs[i + 1] == null) { | |
| 182 write(' › ${breadcrumbs[i]}'); | |
| 183 } else { | |
| 184 write(' › ${a(breadcrumbs[i + 1], breadcrumbs[i])}'); | |
| 185 } | |
| 186 } | |
| 187 writeln('</div>'); | |
| 188 | |
| 159 docNavigation(); | 189 docNavigation(); |
| 160 writeln('<div class="content">'); | 190 writeln('<div class="content">'); |
| 161 } | 191 } |
| 162 | 192 |
| 163 writeFooter() { | 193 writeFooter() { |
| 164 writeln( | 194 writeln( |
| 165 ''' | 195 ''' |
| 166 </div> | 196 </div> |
| 167 <div class="footer"</div> | 197 <div class="footer"</div> |
| 168 </body></html> | 198 </body></html> |
| 169 '''); | 199 '''); |
| 170 } | 200 } |
| 171 | 201 |
| 172 docIndex() { | 202 docIndex() { |
| 173 startFile('index.html'); | 203 startFile('index.html'); |
| 174 | 204 |
| 175 writeHeader('Dart Documentation'); | 205 writeHeader(mainTitle, []); |
| 176 | 206 |
| 177 writeln('<h1>Dart Documentation</h1>'); | 207 writeln('<h2>$mainTitle</h2>'); |
| 178 writeln('<h3>Libraries</h3>'); | 208 writeln('<h3>Libraries</h3>'); |
| 179 | 209 |
| 180 for (final library in orderByName(world.libraries)) { | 210 for (final library in orderByName(world.libraries)) { |
| 181 writeln( | 211 writeln( |
| 182 ''' | 212 ''' |
| 183 <h4>${a(libraryUrl(library), library.name)}</h4> | 213 <h4>${a(libraryUrl(library), library.name)}</h4> |
| 184 '''); | 214 '''); |
| 185 } | 215 } |
| 186 | 216 |
| 187 writeFooter(); | 217 writeFooter(); |
| 188 endFile(); | 218 endFile(); |
| 189 } | 219 } |
| 190 | 220 |
| 191 docNavigation() { | 221 docNavigation() { |
| 192 writeln( | 222 writeln( |
| 193 ''' | 223 ''' |
| 194 <div class="nav"> | 224 <div class="nav"> |
| 195 <h1>${a("index.html", "Dart Documentation")}</h1> | |
| 196 '''); | 225 '''); |
| 197 | 226 |
| 198 for (final library in orderByName(world.libraries)) { | 227 for (final library in orderByName(world.libraries)) { |
| 199 write('<h2><div class="icon-library"></div>'); | 228 write('<h2><div class="icon-library"></div>'); |
| 200 | 229 |
| 201 if ((_currentLibrary == library) && (_currentType == null)) { | 230 if ((_currentLibrary == library) && (_currentType == null)) { |
| 202 write('<strong>${library.name}</strong>'); | 231 write('<strong>${library.name}</strong>'); |
| 203 } else { | 232 } else { |
| 204 write('${a(libraryUrl(library), library.name)}'); | 233 write('${a(libraryUrl(library), library.name)}'); |
| 205 } | 234 } |
| (...skipping 43 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
| 249 exceptions.forEach((type) => writeType('exception', type)); | 278 exceptions.forEach((type) => writeType('exception', type)); |
| 250 writeln('</ul>'); | 279 writeln('</ul>'); |
| 251 } | 280 } |
| 252 | 281 |
| 253 docLibrary(Library library) { | 282 docLibrary(Library library) { |
| 254 _totalLibraries++; | 283 _totalLibraries++; |
| 255 _currentLibrary = library; | 284 _currentLibrary = library; |
| 256 _currentType = null; | 285 _currentType = null; |
| 257 | 286 |
| 258 startFile(libraryUrl(library)); | 287 startFile(libraryUrl(library)); |
| 259 writeHeader(library.name); | 288 writeHeader(library.name, [library.name, libraryUrl(library)]); |
| 260 writeln('<h1>Library <strong>${library.name}</strong></h1>'); | 289 writeln('<h2>Library <strong>${library.name}</strong></h2>'); |
| 261 | 290 |
| 262 // Look for a comment for the entire library. | 291 // Look for a comment for the entire library. |
| 263 final comment = _comments.findLibrary(library.baseSource); | 292 final comment = _comments.findLibrary(library.baseSource); |
| 264 if (comment != null) { | 293 if (comment != null) { |
| 265 final html = md.markdownToHtml(comment); | 294 final html = md.markdownToHtml(comment); |
| 266 writeln('<div class="doc">$html</div>'); | 295 writeln('<div class="doc">$html</div>'); |
| 267 } | 296 } |
| 268 | 297 |
| 269 // Document the top-level members. | 298 // Document the top-level members. |
| 270 docMembers(library.topType); | 299 docMembers(library.topType); |
| (...skipping 46 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
| 317 } | 346 } |
| 318 | 347 |
| 319 docType(Type type) { | 348 docType(Type type) { |
| 320 _totalTypes++; | 349 _totalTypes++; |
| 321 _currentType = type; | 350 _currentType = type; |
| 322 | 351 |
| 323 startFile(typeUrl(type)); | 352 startFile(typeUrl(type)); |
| 324 | 353 |
| 325 final typeTitle = | 354 final typeTitle = |
| 326 '${type.isClass ? "Class" : "Interface"} ${typeName(type)}'; | 355 '${type.isClass ? "Class" : "Interface"} ${typeName(type)}'; |
| 327 writeHeader('Library ${type.library.name} / $typeTitle'); | 356 writeHeader('Library ${type.library.name} / $typeTitle', |
| 357 [type.library.name, libraryUrl(type.library), | |
| 358 typeName(type), typeUrl(type)]); | |
| 328 writeln( | 359 writeln( |
| 329 ''' | 360 ''' |
| 330 <h1>${a(libraryUrl(type.library), | |
| 331 "Library <strong>${type.library.name}</strong>")}</h1> | |
| 332 <h2>${type.isClass ? "Class" : "Interface"} | 361 <h2>${type.isClass ? "Class" : "Interface"} |
| 333 <strong>${typeName(type, showBounds: true)}</strong></h2> | 362 <strong>${typeName(type, showBounds: true)}</strong></h2> |
| 334 '''); | 363 '''); |
| 335 | 364 |
| 336 docInheritance(type); | 365 docInheritance(type); |
| 337 | 366 |
| 338 docCode(type.span, getTypeComment(type)); | 367 docCode(type.span, getTypeComment(type)); |
| 339 docConstructors(type); | 368 docConstructors(type); |
| 340 docMembers(type); | 369 docMembers(type); |
| 341 | 370 |
| (...skipping 440 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
| 782 | 811 |
| 783 return new md.Element.text('code', name); | 812 return new md.Element.text('code', name); |
| 784 } | 813 } |
| 785 | 814 |
| 786 // TODO(rnystrom): Move into SourceSpan? | 815 // TODO(rnystrom): Move into SourceSpan? |
| 787 int getSpanColumn(SourceSpan span) { | 816 int getSpanColumn(SourceSpan span) { |
| 788 final line = span.file.getLine(span.start); | 817 final line = span.file.getLine(span.start); |
| 789 return span.file.getColumn(line, span.start); | 818 return span.file.getColumn(line, span.start); |
| 790 } | 819 } |
| 791 } | 820 } |
| OLD | NEW |
