Doc generation improvements.

pq · pq · commit 659448d82d48 · 2016-02-19T11:06:41.000-08:00
Besides a bit of cleanup, introduces an options file template. BUG= R=keertip@google.com Review URL: https://codereview.chromium.org//1710213003 .
diff --git a/tool/doc.dart b/tool/doc.dart
@@ -38,13 +38,23 @@ void main([args]) {
 
   // Generate rule files
   rules.forEach((l) => new Generator(l).generate(outDir));
+
+  // Generate options samples.
+  new OptionsSample(rules).generate(outDir);
 }
 
 const ruleFootMatter = '''
 In addition, rules can be further distinguished by *maturity*.  Unqualified
 rules are considered stable, while others may be marked **experimental** 
 to indicate that they are under review.
 
+Rules can be selectively enabled in the analyzer using
+[analysis options](https://pub.dartlang.org/packages/analyzer).  An
+auto-generated list enabling all options is provided
+[here](options/options.html).  As some lints may contradict each other, only
+some lints will be enabled in practice, but this list should provide a
+convenient jumping-off point.
+
 These rules are under active development.  Feedback is 
 [welcome](https://github.com/dart-lang/linter/issues)!
 ''';
@@ -75,6 +85,8 @@ String get enumerateStyleRules => rules
     .map((r) => '${toDescription(r)}')
     .join('\n\n');
 
+List<String> get sortedRules => rules.map((r) => r.name).toList()..sort();
+
 void printUsage(ArgParser parser, [String error]) {
   var message = 'Generates lint docs.';
   if (error != null) {
@@ -87,7 +99,8 @@ ${parser.usage}
 ''');
 }
 
-String qualify(LintRule r) => r.name.toString() +
+String qualify(LintRule r) =>
+    r.name.toString() +
     (r.maturity == Maturity.stable ? '' : ' (${r.maturity.name})');
 
 String toDescription(LintRule r) =>
@@ -142,9 +155,9 @@ class Generator {
             </ul>
          </header>
          <section>
-  
+
             ${markdownToHtml(details)}
-          
+
          </section>
       </div>
       <footer>
@@ -228,7 +241,95 @@ class Indexer {
             <h2 id="styleguide-rules">Pub Rules</h2>
 
                $enumeratePubRules
-            
+
+         </section>
+      </div>
+      <footer>
+         <p>Project maintained by <a href="https://github.com/google">google</a></p>
+         <p>Hosted on GitHub Pages &mdash; Theme by <a href="https://github.com/orderedlist">orderedlist</a></p>
+      </footer>
+      <!--[if !IE]><script>fixScale(document);</script><![endif]-->
+      <script type="text/javascript">
+         var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
+         document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
+      </script>
+      <script type="text/javascript">
+         try {
+           var pageTracker = _gat._getTracker("UA-34425814-2");
+         pageTracker._trackPageview();
+         } catch(err) {}
+      </script>
+   </body>
+</html>
+''';
+}
+
+class OptionsSample {
+  Iterable<LintRule> rules;
+  OptionsSample(this.rules);
+
+  generate(String filePath) {
+    var generated = _generate();
+    if (filePath != null) {
+      var outPath = '$filePath/options/options.html';
+      print('Writing to $outPath');
+      new File(outPath).writeAsStringSync(generated);
+    } else {
+      print(generated);
+    }
+  }
+
+  String generateOptions() {
+    StringBuffer sb = new StringBuffer('''
+```
+linter:
+  rules:
+''');
+    for (String rule in sortedRules) {
+      sb.write('    - $rule\n');
+    }
+    sb.write('```');
+
+    return sb.toString();
+  }
+
+  String _generate() => '''
+<!doctype html>
+<html>
+   <head>
+      <meta charset="utf-8">
+      <meta http-equiv="X-UA-Compatible" content="chrome=1">
+      <title>Analysis Options</title>
+      <link rel="stylesheet" href="../../stylesheets/styles.css">
+      <link rel="stylesheet" href="../../stylesheets/pygment_trac.css">
+      <script src="../../javascripts/scale.fix.js"></script>
+      <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
+      <!--[if lt IE 9]>
+      <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
+      <![endif]-->
+   </head>
+  <body>
+      <div class="wrapper">
+         <header>
+            <a href="http://dart-lang.github.io/linter/">
+               <h1>Dart Lint</h1>
+            </a>
+            <p>Analysis Options</p>
+            <p class="view"><a href="https://github.com/dart-lang/linter">View the Project on GitHub <small>dart-lang/linter</small></a></p>
+            <ul>
+              <li><a href="http://dart-lang.github.io/linter/lints/">List of <strong>Lint Rules</strong></a></li>
+              <li><a href="https://github.com/dart-lang/linter">View On <strong>GitHub</strong></a></li>
+            </ul>
+         </header>
+         <section>
+
+            <h1 id="analysis-options">Analysis Options</h1>
+            <p>
+               Auto-generated options enabling all lints; tailor to fit!
+            </p>
+
+${markdownToHtml(generateOptions())}
+
          </section>
       </div>
       <footer>
