Doc generation improvements.
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
index 8ef786f..592d6e8 100644
--- a/tool/doc.dart
+++ b/tool/doc.dart
@@ -38,6 +38,9 @@
// Generate rule files
rules.forEach((l) => new Generator(l).generate(outDir));
+
+ // Generate options samples.
+ new OptionsSample(rules).generate(outDir);
}
const ruleFootMatter = '''
@@ -45,6 +48,13 @@
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 @@
.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 @@
''');
}
-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 @@
</ul>
</header>
<section>
-
+
${markdownToHtml(details)}
-
+
</section>
</div>
<footer>
@@ -228,7 +241,95 @@
<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 — 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>
