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 * This generates the reference documentation for the core libraries that come | 6 * This generates the reference documentation for the core libraries that come |
7 * with dart. It is built on top of dartdoc, which is a general-purpose library | 7 * with dart. It is built on top of dartdoc, which is a general-purpose library |
8 * for generating docs from any Dart code. This library extends that to include | 8 * for generating docs from any Dart code. This library extends that to include |
9 * additional information and styling specific to our standard library. | 9 * additional information and styling specific to our standard library. |
10 * | 10 * |
(...skipping 10 matching lines...) Expand all Loading... |
21 #import('../../frog/file_system.dart'); | 21 #import('../../frog/file_system.dart'); |
22 #import('../../lib/dartdoc/dartdoc.dart', prefix: 'doc'); | 22 #import('../../lib/dartdoc/dartdoc.dart', prefix: 'doc'); |
23 | 23 |
24 HtmlDiff _diff; | 24 HtmlDiff _diff; |
25 | 25 |
26 final GET_PREFIX = 'get:'; | 26 final GET_PREFIX = 'get:'; |
27 | 27 |
28 void main() { | 28 void main() { |
29 final args = new Options().arguments; | 29 final args = new Options().arguments; |
30 | 30 |
| 31 int mode = doc.MODE_STATIC; |
31 var outputDir = 'docs'; | 32 var outputDir = 'docs'; |
32 | 33 |
33 // Use the output directory if provided. | 34 // Use the output directory if provided. |
34 if (args.length > 1) { | 35 |
35 print('Usage: apidoc [--out=<output directory>]'); | 36 for (int i = 0; i < args.length - 1; i++) { |
36 return; | 37 final arg = args[i]; |
37 } else if (args.length == 1) { | 38 |
38 final arg = args[0]; | 39 switch (arg) { |
39 if (arg.startsWith('--out=')) { | 40 case '--mode=static': |
40 outputDir = arg.substring('--out='.length); | 41 mode = doc.MODE_STATIC; |
41 } else { | 42 break; |
42 print('Unknown option: $arg'); | 43 |
43 return; | 44 case '--mode=live-nav': |
| 45 mode = doc.MODE_LIVE_NAV; |
| 46 break; |
| 47 |
| 48 default: |
| 49 if (arg.startsWith('--out=')) { |
| 50 outputDir = arg.substring('--out='.length); |
| 51 } else { |
| 52 print('Unknown option: $arg'); |
| 53 return; |
| 54 } |
| 55 break; |
44 } | 56 } |
45 } | 57 } |
46 | 58 |
47 final frogPath = joinPaths(doc.scriptDir, '../../frog/'); | 59 final frogPath = joinPaths(doc.scriptDir, '../../frog/'); |
| 60 final compilerPath = joinPaths(frogPath, 'minfrog'); |
| 61 final libDir = joinPaths(frogPath, 'lib'); |
48 | 62 |
49 doc.cleanOutputDirectory(outputDir); | 63 doc.cleanOutputDirectory(outputDir); |
50 | 64 |
51 // Compile the client-side code to JS. | 65 // Compile the client-side code to JS. |
52 // TODO(bob): Right path. | 66 // TODO(bob): Right path. |
53 doc.compileScript(frogPath, | 67 |
54 '${doc.scriptDir}/../../lib/dartdoc/client-live-nav.dart', | 68 final clientScript = (mode == doc.MODE_STATIC) ? |
55 '${outputDir}/client-live-nav.js'); | 69 'static' : 'live-nav'; |
| 70 doc.compileScript(compilerPath, libDir, |
| 71 '${doc.scriptDir}/../../lib/dartdoc/client-$clientScript.dart', |
| 72 '${outputDir}/client-$clientScript.js'); |
56 | 73 |
57 // TODO(rnystrom): Use platform-specific path separator. | 74 // TODO(rnystrom): Use platform-specific path separator. |
58 // The basic dartdoc-provided static content. | 75 // The basic dartdoc-provided static content. |
59 doc.copyFiles('${doc.scriptDir}/../../lib/dartdoc/static', outputDir); | 76 doc.copyFiles('${doc.scriptDir}/../../lib/dartdoc/static', outputDir); |
60 | 77 |
61 // The apidoc-specific static content. | 78 // The apidoc-specific static content. |
62 doc.copyFiles('${doc.scriptDir}/static', outputDir); | 79 doc.copyFiles('${doc.scriptDir}/static', outputDir); |
63 | 80 |
64 var files = new VMFileSystem(); | 81 var files = new VMFileSystem(); |
65 parseOptions(frogPath, ['', '', '--libdir=$frogPath/lib'], files); | 82 parseOptions(frogPath, ['', '', '--libdir=$frogPath/lib'], files); |
(...skipping 14 matching lines...) Expand all Loading... |
80 world.getOrAddLibrary('dart:json'); | 97 world.getOrAddLibrary('dart:json'); |
81 world.getOrAddLibrary('dart:dom'); | 98 world.getOrAddLibrary('dart:dom'); |
82 world.getOrAddLibrary('dart:html'); | 99 world.getOrAddLibrary('dart:html'); |
83 world.getOrAddLibrary('dart:io'); | 100 world.getOrAddLibrary('dart:io'); |
84 world.getOrAddLibrary('dart:isolate'); | 101 world.getOrAddLibrary('dart:isolate'); |
85 world.getOrAddLibrary('dart:uri'); | 102 world.getOrAddLibrary('dart:uri'); |
86 world.getOrAddLibrary('dart:utf'); | 103 world.getOrAddLibrary('dart:utf'); |
87 world.process(); | 104 world.process(); |
88 | 105 |
89 print('Generating docs...'); | 106 print('Generating docs...'); |
90 final apidoc = new Apidoc(mdn, outputDir); | 107 final apidoc = new Apidoc(mdn, outputDir, mode); |
91 apidoc.document(); | 108 apidoc.document(); |
92 } | 109 } |
93 | 110 |
94 class Apidoc extends doc.Dartdoc { | 111 class Apidoc extends doc.Dartdoc { |
95 /** Big ball of JSON containing the scraped MDN documentation. */ | 112 /** Big ball of JSON containing the scraped MDN documentation. */ |
96 final Map mdn; | 113 final Map mdn; |
97 | 114 |
| 115 static final disqusShortname = 'dartapidocs'; |
| 116 |
98 /** | 117 /** |
99 * The URL to the page on MDN that content was pulled from for the current | 118 * The URL to the page on MDN that content was pulled from for the current |
100 * type being documented. Will be `null` if the type doesn't use any MDN | 119 * type being documented. Will be `null` if the type doesn't use any MDN |
101 * content. | 120 * content. |
102 */ | 121 */ |
103 String mdnUrl; | 122 String mdnUrl; |
104 | 123 |
105 Apidoc(this.mdn, String outputDir) { | 124 Apidoc(this.mdn, String outputDir, int mode) { |
106 this.outputDir = outputDir; | 125 this.outputDir = outputDir; |
| 126 this.mode = mode; |
107 | 127 |
108 mainTitle = 'Dart API Reference'; | 128 mainTitle = 'Dart API Reference'; |
109 mainUrl = 'http://dartlang.org'; | 129 mainUrl = 'http://dartlang.org'; |
110 | 130 |
111 final note = 'http://code.google.com/policies.html#restrictions'; | 131 final note = 'http://code.google.com/policies.html#restrictions'; |
112 final cca = 'http://creativecommons.org/licenses/by/3.0/'; | 132 final cca = 'http://creativecommons.org/licenses/by/3.0/'; |
113 final bsd = 'http://code.google.com/google_bsd_license.html'; | 133 final bsd = 'http://code.google.com/google_bsd_license.html'; |
114 final tos = 'http://www.dartlang.org/tos.html'; | 134 final tos = 'http://www.dartlang.org/tos.html'; |
115 final privacy = 'http://www.google.com/intl/en/privacy/privacy-policy.html'; | 135 final privacy = 'http://www.google.com/intl/en/privacy/privacy-policy.html'; |
116 | 136 |
117 footerText = | 137 footerText = |
118 ''' | 138 ''' |
119 <p>Except as otherwise <a href="$note">noted</a>, the content of this | 139 <p>Except as otherwise <a href="$note">noted</a>, the content of this |
120 page is licensed under the <a href="$cca">Creative Commons Attribution | 140 page is licensed under the <a href="$cca">Creative Commons Attribution |
121 3.0 License</a>, and code samples are licensed under the | 141 3.0 License</a>, and code samples are licensed under the |
122 <a href="$bsd">BSD License</a>.</p> | 142 <a href="$bsd">BSD License</a>.</p> |
| 143 <p> |
| 144 Comments that are not specifically about the API libraries will |
| 145 be moderated and possibly deleted. |
| 146 Because we may incorporate information from comments into the |
| 147 documentation, any comment submitted here is under the same |
| 148 license as the documentation. |
| 149 </p> |
123 <p><a href="$tos">Terms of Service</a> | | 150 <p><a href="$tos">Terms of Service</a> | |
124 <a href="$privacy">Privacy Policy</a></p> | 151 <a href="$privacy">Privacy Policy</a></p> |
125 '''; | 152 '''; |
126 | 153 |
| 154 preFooterText = |
| 155 ''' |
| 156 <div id="comments"> |
| 157 <div id="disqus_thread"></div> |
| 158 <script type="text/javascript"> |
| 159 /* * * CONFIGURATION VARIABLES: EDIT BEFORE PASTING INTO YOUR WEBPAG
E * * */ |
| 160 var disqus_shortname = "$disqusShortname"; // required: replace exam
ple with your forum shortname |
| 161 |
| 162 /* * * DON\'T EDIT BELOW THIS LINE * * */ |
| 163 (function() { |
| 164 var dsq = document.createElement("script"); dsq.type = "text/jav
ascript"; dsq.async = true; |
| 165 dsq.src = "http://" + disqus_shortname + ".disqus.com/embed.js"; |
| 166 (document.getElementsByTagName("head")[0] || document.getElement
sByTagName("body")[0]).appendChild(dsq); |
| 167 })(); |
| 168 </script> |
| 169 <noscript>Please enable JavaScript to view the <a href="http://disqus.co
m/?ref_noscript">comments powered by Disqus.</a></noscript> |
| 170 </div> <!-- #comments --> |
| 171 '''; |
| 172 |
127 searchEngineId = '011220921317074318178:i4mscbaxtru'; | 173 searchEngineId = '011220921317074318178:i4mscbaxtru'; |
128 searchResultsUrl = 'http://www.dartlang.org/search.html'; | 174 searchResultsUrl = 'http://www.dartlang.org/search.html'; |
129 } | 175 } |
130 | 176 |
131 void writeHeadContents(String title) { | 177 void writeHeadContents(String title) { |
132 super.writeHeadContents(title); | 178 super.writeHeadContents(title); |
133 | 179 |
134 // Include the apidoc-specific CSS. | 180 // Include the apidoc-specific CSS. |
135 // TODO(rnystrom): Use our CSS pre-processor to combine these. | 181 // TODO(rnystrom): Use our CSS pre-processor to combine these. |
136 writeln( | 182 writeln( |
(...skipping 297 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
434 return | 480 return |
435 ''' | 481 ''' |
436 <p class="correspond">This corresponds to $domTypesText in the | 482 <p class="correspond">This corresponds to $domTypesText in the |
437 ${a("dom.html", "dart:dom")} library.</p> | 483 ${a("dom.html", "dart:dom")} library.</p> |
438 '''; | 484 '''; |
439 } | 485 } |
440 | 486 |
441 return ''; | 487 return ''; |
442 } | 488 } |
443 } | 489 } |
OLD | NEW |