Group expressions in generated docs

mapbox · Sep 21, 2017 · fea568f · fea568f
1 parent 3ab6d1a
commit fea568f
Show file tree

Hide file tree

Showing 5 changed files with 197 additions and 100 deletions.
diff --git a/.../style-spec/_generate/expression-types.js → ...yle-spec/_generate/expression-metadata.js b/.../style-spec/_generate/expression-types.js → ...yle-spec/_generate/expression-metadata.js
@@ -1,13 +1,14 @@
 'use strict';
 require('flow-remove-types/register');
 
+const ref = require('../../../src/style-spec/reference/latest');
 const toString = require('../../../src/style-spec/function/types').toString;
 const CompoundExpression = require('../../../src/style-spec/function/compound_expression').CompoundExpression;
 
 // registers compound expressions
 require('../../../src/style-spec/function/definitions');
 
-const results = {
+const types = {
     string: [{
         type: 'String',
         parameters: ['Value']
@@ -114,12 +115,12 @@ const results = {
 for (const name in CompoundExpression.definitions) {
     const definition = CompoundExpression.definitions[name];
     if (Array.isArray(definition)) {
-        results[name] = [{
+        types[name] = [{
             type: toString(definition[0]),
             parameters: processParameters(definition[1])
         }];
     } else {
-        results[name] = definition.overloads.map((o) => {
+        types[name] = definition.overloads.map((o) => {
             return {
                 type: toString(definition.type),
                 parameters: processParameters(o[0])
@@ -128,7 +129,21 @@ for (const name in CompoundExpression.definitions) {
     }
 }
 
-delete results['error'];
+delete types['error'];
+
+const expressions = {};
+const expressionGroups = {};
+for (const name in types) {
+    const spec = ref['expression_name'].values[name];
+    expressionGroups[spec.group] = expressionGroups[spec.group] || [];
+    expressionGroups[spec.group].push(name);
+
+    expressions[name] = {
+        name: name,
+        doc: spec.doc,
+        type: types[name]
+    };
+}
 
 function processParameters(params) {
     if (Array.isArray(params)) {
@@ -138,4 +153,4 @@ function processParameters(params) {
     }
 }
 
-module.exports = results;
+module.exports = {expressions, expressionGroups};
diff --git a/docs/style-spec/_generate/expression.html b/docs/style-spec/_generate/expression.html
@@ -1,8 +1,8 @@
 <div class='col12 clearfix pad0y pad2x space-top0'>
   <span class='space-right'>
-    <%= md("<a class='code' id='types-expression-" + name + "' href='#types-expression-" + name + "'>" + name + "</a> " + (expressionDocs[name] ? ('<br>' + expressionDocs[name].doc) : '').trim()) %>
+    <%= md("<a class='code' id='types-expression-" + name + "' href='#types-expression-" + name + "'>" + name + "</a> " + (doc ? ('<br>' + doc) : '').trim()) %>
   </span>
-  <% for (const overload of expressionTypes[name]) { %>
+  <% for (const overload of type) { %>
     <div>
 {% highlight javascript %}
 <%=renderSignature(name, overload) %>

diff --git a/docs/style-spec/_generate/generate.js b/docs/style-spec/_generate/generate.js
@@ -2,44 +2,62 @@
 
 // GL style reference generator
 
-var fs = require('fs');
-var path = require('path');
-var ref = require('../../../src/style-spec/reference/latest');
-var _ = require('lodash');
-var remark = require('remark');
-var html = require('remark-html');
+const fs = require('fs');
+const path = require('path');
+const assert = require('assert');
+const ref = require('../../../src/style-spec/reference/latest');
+const _ = require('lodash');
+const remark = require('remark');
+const html = require('remark-html');
 
-var expressionTypes = require('./expression-types');
+const {expressions, expressionGroups} = require('./expression-metadata');
 
+const groupedExpressions = [
+    'Types',
+    'Feature data',
+    'Lookup',
+    'Decision',
+    'Ramps, scales, curves',
+    'Variable binding',
+    'String',
+    'Color',
+    'Math',
+    'Zoom'
+].map(group => ({
+    name: group,
+    expressions: expressionGroups[group]
+        .sort((a, b) => a.localeCompare(b))
+        .map(name => expressions[name])
+}));
+
+assert(groupedExpressions.length === Object.keys(expressionGroups).length, 'All expression groups accounted for in generated docs');
 
 function tmpl(x, options) {
     return _.template(fs.readFileSync(path.join(__dirname, x), 'utf-8'), options);
 }
 
-var index = tmpl('index.html', {
-  imports: {
-    _: _,
-    item: tmpl('item.html', {
-      imports: {
-        _: _,
-        md: function(markdown) {
-          return remark().use(html).process(markdown);
-        }
-      }
-    }),
-    expressions: Object.keys(expressionTypes).sort((a, b) => a.localeCompare(b)),
-    renderExpression: tmpl('expression.html', {
-      imports: {
+const index = tmpl('index.html', {
+    imports: {
         _: _,
-        expressionDocs: ref['expression_name'].values,
-        expressionTypes: expressionTypes,
-        renderSignature: renderSignature,
-        md: function(markdown) {
-          return remark().use(html).process(markdown)
-        }
-      }
-    })
-  }
+        item: tmpl('item.html', {
+            imports: {
+                _: _,
+                md: function(markdown) {
+                    return remark().use(html).process(markdown);
+                }
+            }
+        }),
+        groupedExpressions: groupedExpressions,
+        renderExpression: tmpl('expression.html', {
+            imports: {
+                _: _,
+                renderSignature: renderSignature,
+                md: function(markdown) {
+                    return remark().use(html).process(markdown);
+                }
+            }
+        })
+    }
 });
 
 function renderSignature (name, overload) {

diff --git a/docs/style-spec/_generate/index.html b/docs/style-spec/_generate/index.html
@@ -1020,8 +1020,11 @@ <h4>Example: a zoom-and-property function</h4>
         <div class='pad2 keyline-bottom'>
           <a id='types-expression' class='anchor'></a>
           <h3 class='space-bottom1'><a href='#types-expression' title='link to expression'>Expression</a></h3>
-          <% for (var name of expressions) { %>
-            <%= renderExpression({name: name}) %>
+          <% for (var group of groupedExpressions) { %>
+            <h4 style='font-size: 100%'><a id='types-expression-group-<%= group.name %>' href='#types-expression-group-<%= group.name %>'><%= group.name %></a></h4>
+            <% for (var expression of group.expressions) { %>
+              <%= renderExpression(expression) %>
+            <% } %>
           <% } %>
         </div>