Use JS & Jade to generate the customizer variables form HTML from variables.less; fixes #11095

also updates variables file organization (courtesy @mdo)

Gruntfile.js

@@ -10,9 +10,11 @@ module.exports = function (grunt) {
     return string.replace(/[-\\^$*+?.()|[\]{}]/g, '\\$&')
   }
 
+  var BsLessdocParser = require('./docs/grunt/bs-lessdoc-parser.js')
   var fs = require('fs')
   var generateGlyphiconsData = require('./docs/grunt/bs-glyphicons-data-generator.js')
   var generateRawFilesJs = require('./docs/grunt/bs-raw-files-generator.js')
+  var path = require('path')
 
   // Project configuration.
   grunt.initConfig({
@@ -46,6 +48,9 @@ module.exports = function (grunt) {
       },
       assets: {
         src: ['docs/assets/js/application.js', 'docs/assets/js/customizer.js']
+      },
+      docsGrunt: {
+        src: ['docs/grunt/*.js']
       }
     },
 
@@ -64,6 +69,9 @@ module.exports = function (grunt) {
       },
       assets: {
         src: ['docs/assets/js/application.js', 'docs/assets/js/customizer.js']
+      },
+      docsGrunt: {
+        src: ['docs/grunt/*.js']
       }
     },
 
@@ -236,6 +244,23 @@ module.exports = function (grunt) {
       docs: {}
     },
 
+    jade: {
+      compile: {
+        options: {
+          pretty: true,
+          data: function () {
+            var filePath = path.join(__dirname, 'less/variables.less');
+            var fileContent = fs.readFileSync(filePath, {encoding: 'utf8'});
+            var parser = new BsLessdocParser(fileContent);
+            return {sections: parser.parseFile()};
+          }
+        },
+        files: {
+          'docs/_includes/customizer-variables.html': 'docs/customizer-variables.jade'
+        }
+      }
+    },
+
     validation: {
       options: {
         charset: 'utf-8',
@@ -301,7 +326,7 @@ module.exports = function (grunt) {
   var testSubtasks = [];
   // Skip core tests if running a different subset of the test suite
   if (!process.env.TWBS_TEST || process.env.TWBS_TEST === 'core') {
-    testSubtasks = testSubtasks.concat(['dist-css', 'csslint', 'jshint', 'jscs', 'qunit']);
+    testSubtasks = testSubtasks.concat(['dist-css', 'csslint', 'jshint', 'jscs', 'qunit', 'build-customizer-vars-form']);
   }
   // Skip HTML validation if running a different subset of the test suite
   if (!process.env.TWBS_TEST || process.env.TWBS_TEST === 'validate-html') {
@@ -339,5 +364,7 @@ module.exports = function (grunt) {
   grunt.registerTask('build-glyphicons-data', generateGlyphiconsData);
 
   // task for building customizer
-  grunt.registerTask('build-customizer', 'Add scripts/less files to customizer.', generateRawFilesJs);
+  grunt.registerTask('build-customizer', ['build-customizer-vars-form', 'build-raw-files']);
+  grunt.registerTask('build-customizer-vars-form', ['jade']);
+  grunt.registerTask('build-raw-files', 'Add scripts/less files to customizer.', generateRawFilesJs);
 };

docs/assets/css/docs.css

@@ -1161,6 +1161,13 @@ h1[id] {
   font-weight: normal;
 }
 
+.bs-customizer-input {
+  float: left;
+  width: 33.333333%;
+  padding-left: 15px;
+  padding-right: 15px;
+}
+
 /* Downloads */
 .bs-customize-download .btn-outline {
   padding: 20px;

docs/customizer-variables.jade

+// NOTE: DO NOT EDIT THE FOLLOWING SECTION DIRECTLY! It is autogenerated via the `build-customizer-vars-form` Grunt task using the customizer-variables.jade template.
+each section in sections
+  if section.customizable
+    h2(id=section.id)= section.heading
+    if section.docstring
+      p!= section.docstring.html
+    div.row
+      each variable in section.variables
+        div.bs-customizer-input
+          label(for="input-" + variable.name)= variable.name
+          input.form-control(
+            id="input-" + variable.name
+            type="text"
+            value=variable.defaultValue
+            data-var=variable.name)
+          if variable.docstring
+            p.help-block!= variable.docstring.html
+// NOTE: DO NOT EDIT THE PRECEDING SECTION DIRECTLY! It is autogenerated via the `build-customizer-vars-form` Grunt task using the customizer-variables.jade template.

docs/grunt/bs-lessdoc-parser.js

+/* jshint node: true */
+
+var markdown = require('markdown').markdown;
+
+function markdown2html(markdownString) {
+  // the slice removes the <p>...</p> wrapper output by Markdown processor
+  return markdown.toHTML(markdownString.trim()).slice(3, -4);
+}
+
+
+/*
+Mini-language:
+  //== This is a normal heading, which starts a section. Sections group variables together.
+  //## Optional description for the heading
+
+  //** Optional description for the following variable. You **can** use Markdown in descriptions to discuss `<html>` stuff.
+  @foo: #ffff;
+
+  //-- This is a heading for a section whose variables shouldn't be customizable
+
+  All other lines are ignored completely.
+*/
+
+
+var CUSTOMIZABLE_HEADING = /^[/]{2}={2}(.*)$/;
+var UNCUSTOMIZABLE_HEADING = /^[/]{2}-{2}(.*)$/;
+var SECTION_DOCSTRING = /^[/]{2}#{2}(.*)$/;
+var VAR_ASSIGNMENT = /^(@[a-zA-Z0-9_-]+):[ ]*([^ ;][^;]+);[ ]*$/;
+var VAR_DOCSTRING = /^[/]{2}[*]{2}(.*)$/;
+
+function Section(heading, customizable) {
+  this.heading = heading.trim();
+  this.id = this.heading.replace(/\s+/g, '-').toLowerCase();
+  this.customizable = customizable;
+  this.docstring = null;
+  this.variables = [];
+  this.addVar = function (variable) {
+    this.variables.push(variable);
+  };
+}
+
+function VarDocstring(markdownString) {
+  this.html = markdown2html(markdownString);
+}
+
+function SectionDocstring(markdownString) {
+  this.html = markdown2html(markdownString);
+}
+
+function Variable(name, defaultValue) {
+  this.name = name;
+  this.defaultValue = defaultValue;
+  this.docstring = null;
+}
+
+function Tokenizer(fileContent) {
+  this._lines = fileContent.split('\n');
+  this._next = undefined;
+}
+
+Tokenizer.prototype.unshift = function (token) {
+  if (this._next !== undefined) {
+    throw new Error('Attempted to unshift twice!');
+  }
+  this._next = token;
+};
+
+Tokenizer.prototype._shift = function () {
+  // returning null signals EOF
+  // returning undefined means the line was ignored
+  if (this._next !== undefined) {
+    var result = this._next;
+    this._next = undefined;
+    return result;
+  }
+  if (this._lines.length <= 0) {
+    return null;
+  }
+  var line = this._lines.shift();
+  var match = null;
+  match = CUSTOMIZABLE_HEADING.exec(line);
+  if (match !== null) {
+    return new Section(match[1], true);
+  }
+  match = UNCUSTOMIZABLE_HEADING.exec(line);
+  if (match !== null) {
+    return new Section(match[1], false);
+  }
+  match = SECTION_DOCSTRING.exec(line);
+  if (match !== null) {
+    return new SectionDocstring(match[1]);
+  }
+  match = VAR_DOCSTRING.exec(line);
+  if (match !== null) {
+    return new VarDocstring(match[1]);
+  }
+  var commentStart = line.lastIndexOf('//');
+  var varLine = (commentStart === -1) ? line : line.slice(0, commentStart);
+  match = VAR_ASSIGNMENT.exec(varLine);
+  if (match !== null) {
+    return new Variable(match[1], match[2]);
+  }
+  return undefined;
+};
+
+Tokenizer.prototype.shift = function () {
+  while (true) {
+    var result = this._shift();
+    if (result === undefined) {
+      continue;
+    }
+    return result;
+  }
+};
+
+function Parser(fileContent) {
+  this._tokenizer = new Tokenizer(fileContent);
+}
+
+Parser.prototype.parseFile = function () {
+  var sections = [];
+  while (true) {
+    var section = this.parseSection();
+    if (section === null) {
+      if (this._tokenizer.shift() !== null) {
+        throw new Error('Unexpected unparsed section of file remains!');
+      }
+      return sections;
+    }
+    sections.push(section);
+  }
+};
+
+Parser.prototype.parseSection = function () {
+  var section = this._tokenizer.shift();
+  if (section === null) {
+    return null;
+  }
+  if (!(section instanceof Section)) {
+    throw new Error('Expected section heading; got: ' + JSON.stringify(section));
+  }
+  var docstring = this._tokenizer.shift();
+  if (docstring instanceof SectionDocstring) {
+    section.docstring = docstring;
+  }
+  else {
+    this._tokenizer.unshift(docstring);
+  }
+  this.parseVars(section);
+  return section;
+};
+
+Parser.prototype.parseVars = function (section) {
+  while (true) {
+    var variable = this.parseVar();
+    if (variable === null) {
+      return;
+    }
+    section.addVar(variable);
+  }
+};
+
+Parser.prototype.parseVar = function () {
+  var docstring = this._tokenizer.shift();
+  if (!(docstring instanceof VarDocstring)) {
+    this._tokenizer.unshift(docstring);
+    docstring = null;
+  }
+  var variable = this._tokenizer.shift();
+  if (variable instanceof Variable) {
+    variable.docstring = docstring;
+    return variable;
+  }
+  this._tokenizer.unshift(variable);
+  return null;
+};
+
+
+module.exports = Parser;

package.json

@@ -33,6 +33,7 @@
     "grunt-contrib-connect": "~0.6.0",
     "grunt-contrib-copy": "~0.5.0",
     "grunt-contrib-csslint": "~0.2.0",
+    "grunt-contrib-jade": "~0.8.0",
     "grunt-contrib-jshint": "~0.8.0",
     "grunt-contrib-less": "~0.9.0",
     "grunt-contrib-qunit": "~0.3.0",
@@ -44,7 +45,8 @@
     "grunt-jscs-checker": "~0.3.0",
     "grunt-saucelabs": "~4.1.2",
     "grunt-sed": "~0.1.1",
-    "load-grunt-tasks": "~0.2.1"
+    "load-grunt-tasks": "~0.2.1",
+    "markdown": "~0.5.0"
   },
   "jspm": {
     "main": "js/bootstrap",