Refactor "options" documentation logic

Use Handlebars partials and helpers to generate the markup for the
"Options" page more declaratively. This requires exposing raw "options"
data during site compilation and will facilitate future extensions to
the interactive code editor displayed on the website's index page.

Author: jugglinmike

package.json

@@ -18,7 +18,6 @@
   },
   "oddwebPlugins": [
     "core/blog",
-    "plugins/options.js",
     "plugins/minify.js",
     "plugins/variables.js"
   ],

pages/options.html

@@ -12,16 +12,16 @@ <h3><a class="anchor" href="#enforcing-options" name="enforcing-options">Enforci
 
 <p>When set to true, these options will make JSHint produce more warnings about your code.</p>
 
-{{show-enforcers}}
+{{>option-table options.enforcers }}
 
 <h3><a class="anchor" href="#relaxing-options" name="relaxing-options">Relaxing options</a></h3>
 
 <p>When set to true, these options will make JSHint produce fewer warnings about your code.</p>
 
-{{show-relaxers}}
+{{>option-table options.relaxers }}
 
 <h3><a class="anchor" href="#environments" name="environments">Environments</a></h3>
 
 <p>These options let JSHint know about some pre-defined global variables.</p>
 
-{{show-environments}}
+{{>option-table options.environments }}

partials/option-table.html

@@ -0,0 +1,19 @@
+<table class='options table table-bordered table-striped'>
+  {{#each this}}
+  <tr>
+    <td class="{{name}}" id="{{name}}">
+      <a href="#{{name}}">{{name}}</a>
+    </td>
+    <td class="desc">
+      {{#if deprecationReason}}
+      <div class="deprecation-msg">
+        <strong>Warning</strong> This option has been deprecated and will be
+        removed in the next major release of JSHint.
+        {{{markdown deprecationReason}}}
+      </div>
+      {{/if}}
+      {{{ description.full }}}
+    </td>
+  </tr>
+  {{/each}}
+</table>

plugins/options.js

@@ -0,0 +1,36 @@
+"use strict";
+var openPattern = /^(\s*)```[\w]*\s*$/;
+var closePattern = /^\s*```\s*$/;
+
+/**
+ * The Markdown preprocessor used by Oddweb does not support the
+ * "backtick"/"code fence" syntax for multiline code examples. If present,
+ * these must be translated to the "indented" format.
+ */
+module.exports = function(markdown) {
+  var lines = markdown.split("\n");
+  var state = { fixed: [], indent: '', isCode: false };
+
+  lines.reduce(function(state, line) {
+    var match;
+    if (state.isCode) {
+      if (closePattern.test(line)) {
+        state.isCode = false;
+      } else {
+        state.fixed.push(state.indent + line);
+      }
+    } else {
+      match = openPattern.exec(line);
+      if (match) {
+        state.isCode = true;
+        state.indent = match[1] || '    ';
+      } else {
+        state.fixed.push(line);
+      }
+    }
+    return state;
+  }, state);
+
+  return state.fixed.join("\n");
+}
+

plugins/util/fenced-code.js

@@ -0,0 +1,78 @@
+"use strict";
+var fs = require("fs");
+
+var dox = require("dox");
+dox.setMarkedOptions({
+  breaks: false
+});
+
+function getCategory(annotation, options) {
+  var value = null;
+  var name = annotation.ctx.name;
+
+  if (name in options.parsed.bool.enforcing || name in options.parsed.val) {
+    name = "enforcers";
+  } else if (name in options.parsed.bool.relaxing) {
+    name = "relaxers";
+  } else if (name in options.parsed.bool.environments) {
+    name = "environments";
+  } else {
+    throw new Error("Category not recognized for option ", name);
+  }
+
+  return name;
+}
+
+function getDeprecationReason(annotation) {
+  var tags = annotation.tags;
+  var idx, length, tag;
+
+  if (!tags) {
+    return null;
+  }
+
+  for (idx = 0, length = tags.length; idx < length; ++idx) {
+    tag = tags[idx];
+    if (tag.type === 'deprecated') {
+      return tag.string;
+    }
+  }
+
+  return null;
+}
+
+module.exports = function(path) {
+  var options = {
+    src: fs.readFileSync(path, { encoding: "utf-8" }),
+    parsed: require(path),
+    byCategory: {
+      enforcers: [],
+      relaxers: [],
+      environments: [],
+      legacy: []
+    }
+  };
+
+  options.annotations = dox.parseComments(options.src);
+
+  options.annotations.map(function(annotation) {
+    var name = annotation.code.split(":")[0];
+    var option = options.parsed[name];
+
+    annotation.name = name.trim();
+    annotation.category = getCategory(annotation, options);
+    annotation.deprecationReason = getDeprecationReason(annotation);
+
+    return annotation;
+  }).forEach(function(annotation) {
+    options.byCategory[annotation.category].push(annotation);
+  });
+
+  Object.keys(options.byCategory).forEach(function(category) {
+    options.byCategory[category].sort(function(a, b) {
+      return a.name > b.name ? 1 : -1;
+    });
+  });
+
+  return options.byCategory;
+};

plugins/util/read-options.js

@@ -5,6 +5,10 @@
 "use strict";
 var path = require("path");
 var fs = require("fs");
+var marked = require("marked");
+var readOptions = require("./util/read-options");
+var translateFencedCode = require("./util/fenced-code");
+var optionsSrc = __dirname + "/../res/jshint/src/options.js";
 
 var pkg = require(path.join(
   __dirname, "..", "res", "jshint", "package.json")
@@ -15,6 +19,7 @@ var contributing = fs.readFileSync(
 var context = {
   contributionGuidelines: translateFencedCode(contributing),
   version: pkg.version,
+  options: readOptions(optionsSrc),
   urls: {
     repo: "https://github.com/jshint/jshint",
     newIssue: "https://github.com/jshint/jshint/issues/new",
@@ -23,41 +28,26 @@ var context = {
   }
 };
 
-/**
- * The Markdown preprocessor used by Oddweb does not support the
- * "backtick"/"code fence" syntax for multiline code examples. If present,
- * these must be translated to the "indented" format.
- */
-function translateFencedCode(markdown) {
-  var openPattern = /^(\s*)```[\w]*\s*$/;
-  var closePattern = /^\s*```\s*$/;
-  var lines = markdown.split("\n");
-  var state = { fixed: [], indent: '', isCode: false };
+module.exports = function (site, handlebars) {
+  var partialPattern = /^(.*)\.html$/i;
+
+  handlebars.registerHelper("markdown", function (input) {
+    return new handlebars.SafeString(marked(input));
+  });
+
+  fs.readdirSync("partials").forEach(function(filename) {
+    var match = filename.match(partialPattern);
 
-  lines.reduce(function(state, line) {
-    var match;
-    if (state.isCode) {
-      if (closePattern.test(line)) {
-        state.isCode = false;
-      } else {
-        state.fixed.push(state.indent + line);
-      }
-    } else {
-      match = openPattern.exec(line);
-      if (match) {
-        state.isCode = true;
-        state.indent = match[1] || '    ';
-      } else {
-        state.fixed.push(line);
-      }
+    if (!match) {
+      return null;
     }
-    return state;
-  }, state);
 
-  return state.fixed.join("\n");
-}
+    handlebars.registerPartial(
+      match[1],
+      fs.readFileSync(path.join("partials", filename), { encoding: "utf-8" })
+    );
+  });
 
-module.exports = function (site, handlebars) {
   site.pages.forEach(function(page) {
     var template = handlebars.compile(page.data);
     page.data = template(context);