Skip to content

Commit

Permalink
Group expressions in generated docs (#5342)
Browse files Browse the repository at this point in the history
  • Loading branch information
anandthakker authored Sep 21, 2017
1 parent 3ab6d1a commit 8fea8d6
Show file tree
Hide file tree
Showing 5 changed files with 197 additions and 100 deletions.
Original file line number Diff line number Diff line change
@@ -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']
Expand Down Expand Up @@ -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])
Expand All @@ -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)) {
Expand All @@ -138,4 +153,4 @@ function processParameters(params) {
}
}

module.exports = results;
module.exports = {expressions, expressionGroups};
4 changes: 2 additions & 2 deletions docs/style-spec/_generate/expression.html
Original file line number Diff line number Diff line change
@@ -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) %>
Expand Down
78 changes: 48 additions & 30 deletions docs/style-spec/_generate/generate.js
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down
7 changes: 5 additions & 2 deletions docs/style-spec/_generate/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -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>

Expand Down
Loading

0 comments on commit 8fea8d6

Please sign in to comment.