added docs to the repo

scripts/generate/js_api.js

@@ -24,7 +24,6 @@ module.exports = function (done) {
     writeApiFile,
     ensureDocsDir,
     formatDocVars,
-    writeMethodList,
     writeMethodDocs
   ], done);
 
@@ -101,17 +100,9 @@ module.exports = function (done) {
     done();
   }
 
-  function writeMethodList(done) {
-    fs.writeFile(
-      '../../docs/_method_list.jade',
-      templates.apiMethodList(docVars),
-      done
-    );
-  }
-
   function writeMethodDocs(done) {
     fs.writeFile(
-      '../../docs/_methods.jade',
+      '../../docs/api_methods.asciidoc',
       templates.apiMethods(docVars),
       done
     );

scripts/generate/templates/api_method_list.tmpl

@@ -1,32 +0,0 @@
-<%
-function esc(str) {
-  return str.replace(/\|/g, '&#124;');
-}
-
-var topActions = [];
-var names = {};
-
-_.each(actions, function (action) {
-  if (action.name.indexOf('.') > -1) {
-    var space = _.studlyCase(action.name.split('.').slice(0, -1).join('.'));
-    if (!names[space]) {
-      names[space] = [];
-    }
-    names[space].push(action);
-  } else {
-    topActions.push(action);
-  }
-}); %>
-
-ul<%
-_.each(topActions, function (action) {%>
-  li: a(href="api.html#<%= action.name.toLowerCase().replace(/[^\w]+/g, '-') %>") <%= action.name %><%
-});
-_.each(Object.keys(names).sort(), function (namespace) {%>
-  h3 <%= namespace %>
-  ul<%
-  _.each(names[namespace], function (action) {%>
-    li: a(href="api.html#<%= action.name.toLowerCase().replace(/[^\w]+/g, '-') %>") <%= action.name.replace(/^.*\./, '') %><%
-  })
-})
-%>

scripts/generate/templates/api_methods.tmpl

@@ -1,27 +1,34 @@
+== API Method Reference
 <%
 _.each(actions, function (action) {
-var actionId = action.name.toLowerCase().replace(/[^\w]+/g, '-');
+var actionId = 'api-' + action.name.toLowerCase().replace(/[^\w]+/g, '-');
 
 %>
 
-h2#<%= actionId %>.fn <%= action.name %>(params, [callback])
-include _descriptions/<%= action.name %>.jade
-p.
-  The default method is <code><%= action.spec.method || 'GET' %></code> and
-  the usual <a href="#api-conventions">params and return values</a> apply.
-  See <a href="<%= action.docUrl %>" title="<%= action.name %>
-  at elasticsearch.org"><%= action.docUrl %></a> for more about this method.
-include _examples/<%= action.name %>.jade
+[[<%= actionId %>]]
+=== `<%= action.name %>`
+
+[source,js]
+--------
+client.<%= action.name %>([params, [callback]])
+--------
+
+<%= description(action.name) %>
+
+The default method is `<%= action.spec.method || 'GET' %>` and the usual <<api-conventions,params and return values>> apply. See <%= action.docUrl %>[the elasticsearch docs] for more about this method.
+
+<%= examples(action.name) %>
+
 <% if (_.size(action.allParams)) { %>
-h3 Params
-dl.params.api
-<% _.each(action.allParams, function (param, paramName) { %>
-  dt: dfn: code <%= paramWithDefault(paramName, param.default) %>
-  dd.
-    <span class="types"><%= paramType(param.type) %></span>
-<%= indent(param.description || '', 4) %><%
-}); %>
-<% }
+==== Params
 
-});
+[horizontal]<%
+_.each(action.allParams, function (param, paramName) { %>
+`<%= paramWithDefault(paramName, param.default) %>`::
+`<%= paramType(param.type) %>` -- <%= joinParagraphs(param.description || '', 4) %><%
+
+  }); // endeach
+} // endif
+
+}); // endeach
 %>

scripts/generate/templates/index.js

@@ -49,6 +49,34 @@ var templateGlobals = {
     }).join('\n');
   },
 
+  joinParagraphs: function (block) {
+    return block.split('\n\n').join('\n+\n');
+  },
+
+  description: function (action) {
+    try {
+      return fs.readFileSync(path.join(__dirname, '../../../docs/_descriptions/' + action + '.asciidoc'));
+    } catch (e) {
+      if (~e.message.indexOf('ENOENT')) {
+        return '// no description';
+      } else {
+        throw e;
+      }
+    }
+  },
+
+  examples: function (action) {
+    try {
+      return fs.readFileSync(path.join(__dirname, '../../../docs/_examples/' + action + '.asciidoc'));
+    } catch (e) {
+      if (~e.message.indexOf('ENOENT')) {
+        return '// no examples';
+      } else {
+        throw e;
+      }
+    }
+  },
+
   paramType: function (type) {
     switch (type && type.toLowerCase ? type.toLowerCase() : 'any') {
     case 'time':

scripts/sync_examples.js

@@ -0,0 +1,72 @@
+var async = require('async');
+var fs = require('fs');
+var S = require('string');
+
+var restSpecDir = './src/rest-api-spec/api/';
+
+function fileExists(path, done) {
+  fs.stat(path, function (err, stats) {
+    var exists;
+
+    if (err) {
+      if (err.message.match(/enoent/i)) {
+        err = void 0;
+        exists = false;
+      }
+    } else if (stats.isFile()) {
+      exists = true;
+    } else {
+      err = new Error('weird stats: ' + JSON.stringify(stats));
+    }
+
+    done(err, exists);
+  });
+}
+
+fs.readdir(restSpecDir, function (err, files) {
+  if (err) {
+    throw err;
+  }
+
+  async.forEachSeries(files, function (fileName, done) {
+    var apiName = S(fileName.replace(/\.json$/, '')).camelize().s;
+    var filePath = './docs/_descriptions/' + apiName;
+    var jadeFileExists;
+    var asciiFileExists;
+
+    async.series([
+      function (done) {
+        fileExists(filePath + '.jade', function (err, exists) {
+          jadeFileExists = exists;
+          done(err);
+        });
+      },
+      function (done) {
+        fileExists(filePath + '.asciidoc', function (err, exists) {
+          asciiFileExists = exists;
+          done(err);
+        });
+      },
+      function (done) {
+        if (jadeFileExists && !asciiFileExists) {
+          console.log(apiName, 'jade, no ascii');
+          fs.rename(filePath + '.jade', filePath + '.asciidoc', done);
+        }
+        else if (!jadeFileExists && !asciiFileExists) {
+          console.log(apiName, 'no jade, no ascii');
+          fs.writeFile(filePath + '.asciidoc', '', done);
+        }
+        else if (jadeFileExists) {
+          console.log(apiName, 'jade');
+          fs.unlink(filePath + '.jade', done);
+        }
+      }
+    ], done);
+  }, function done(err) {
+    if (err) {
+      throw err;
+    } else {
+      console.log('done');
+    }
+  });
+});