Merge pull request OraOpenSource#63 from RamonEsteveCuevas/master

Search engine and structured menu
barsema · Jul 28, 2017 · fd40359 · fd40359
2 parents d8526e1 + dcaa504
commit fd40359
Show file tree

Hide file tree

Showing 13 changed files with 877 additions and 61 deletions.
diff --git a/app.js b/app.js
@@ -4,7 +4,8 @@ var
   Handlebars = require('./lib/handlebars.js'),
   extend = require('node.extend'),
   debug = require('./lib/debug.js'),
-  pmd = require('./lib/pmd.js')(debug, extend)
+  pmd = require('./lib/pmd.js')(debug, extend),
+  search = require('./lib/search.js')(debug, extend)
 ;
 
 
@@ -87,6 +88,10 @@ if (config.toc.template){
 var objs = pmd.generateData(config);
 objs = pmd.mergeObjs(objs);
 
-// First generate the TOC than the files, so the packages also have a TOC
 pmd.generateToc(config, objs);
-pmd.saveToFile(config, objs);
+pmd.saveToFile(config, pmd.globalFiles);
+
+// Check if the search library is enabled
+if(config.search) {
+  search.run(config, pmd.globalFiles);
+}
diff --git a/default.json b/default.json
@@ -1,6 +1,7 @@
 {
   "projectDispName" : "",
   "debug" : false,
+  "search": false,
   "toc" : {
     "fileName" : "index.md"
   },

diff --git a/docs/config.json.md b/docs/config.json.md
@@ -8,6 +8,7 @@ When this project is installed a default `config.json` is generated in the proje
 {
   "<projectName>" : {
     "debug" : false,
+    "search": false,
     "folders" : {
       "output" : {
         "path" : "/Users/giffy/Documents/GitHub/oraopensource/oos-utils/docs"
@@ -33,6 +34,7 @@ Parameter | Required | Description
 --- | --- | ---
 `<projectName>` | required | Unique name of the project.
 `<projectName>.debug` | optional | Default: `false`. Run app in debug mode.
+`<projectName>.search` | optional | Default: `false`. Also enable the search module (only available for HTML templates).
 `<projectName>.folders` | required | single JSON object array of objects. Use the an array if the project has multiple folders to process.
 `<projectName>.folders.output` | required | JSON object for output information
 `<projectName>.folders.output.delete` | optional | Boolean to delete contents in folder. Default `false`.

diff --git a/docs/handlebars.md b/docs/handlebars.md
@@ -31,3 +31,15 @@ Handlebars has basic condition processing. `ifCond` allows for more complex and
 Ex: `{{#ifCond params.length '||' return}}...{{/ifCond}}`
 
 It's notation is `value1, operator, value2`. The `operator` is a string and can be any of the following: `==`, `===`, `<`, `<=`, `>`, `>=`, `&&`, `||`.
+
+### `times`
+
+Executes the body with the amount of times inserted as the first parameter
+
+Ex: `{{times 10}}`
+
+### `now`
+
+Will return the current timestamp
+
+Ex: `{{now}}`
diff --git a/lib/handlebars.js b/lib/handlebars.js
@@ -73,5 +73,18 @@ Handlebars.registerHelper('entityFilter', function(entityType, options) {
   return options.fn(retEntities);
 });
 
+// Register the normal for loop as a helper function inside Handlebars
+Handlebars.registerHelper('times', function(n, block) {
+  var accum = '';
+  for(var i = 0; i < n; ++i)
+    accum += block.fn(i);
+  return accum;
+});
+
+// Gets the current timestamp, used for disabling cached Javascript files, will cache a file until next build
+Handlebars.registerHelper('now', function() {
+  return Date.now();
+});
+
 
 module.exports = Handlebars;
diff --git a/lib/pmd.js b/lib/pmd.js
@@ -3,6 +3,7 @@ var
   debug,
   extend,
   path = require('path'),
+  fsExtra = require("fs-extra"),
   dox = require('./dox.js')
   ;
 
@@ -177,6 +178,7 @@ pmd.processFile = function(file){
           break;
         case 'throws':
           entity.throws.push({
+            name: tag.name,
             description: tag.description.replace(/(^<p>|<\/p>$)/g, '').replace(/(<em>|<\/em>)/g,'')
           });
           break;
@@ -320,7 +322,7 @@ pmd.getArguments = function(process){
 }//getArguments
 
 
-pmd.readFolder = function(objs, config, folder) {
+pmd.readFolder = function(parent, config, folder) {
   var
     files     = fs.readdirSync(path.resolve(folder.source.path)),
     template  = Handlebars.compile(folder.templateContent)
@@ -336,7 +338,21 @@ pmd.readFolder = function(objs, config, folder) {
       newFolder.source.path             += '/' + fileName;
       newFolder.source.fileFilterRegexp = folder.source.fileFilterRegexp;
 
-      pmd.readFolder(objs, config, newFolder);
+      // Get everything after the last slash, to get the name of the folder, and make a Array ready for the children
+      var innerFolder = {
+        fileData: {
+          name: /[^/]*$/.exec(newFolder.source.path)[0],
+          isFolder: true
+        },
+        depth: parent.depth+1,
+        children: []
+      };
+
+      // Add the innerfolder to the parent as a children
+      pmd.readFolder(innerFolder, config, newFolder);
+
+      // Add the folder to the parent
+      parent.children.push(innerFolder);
     }
   });
 
@@ -379,6 +395,10 @@ pmd.readFolder = function(objs, config, folder) {
       file.docFileName = file.name + docExtName;
 
       data.name = file.name;
+      data.path = file.path;
+      data.docFileName = file.docFileName;
+      data.isFolder = false;
+
       entities = pmd.processFile(file, debug);
 
       if(!entities) {
@@ -432,13 +452,13 @@ pmd.readFolder = function(objs, config, folder) {
         debug.logFile(file.name + file.ext + '.json', JSON.stringify(data, null, '  '));
       }
 
-      objs.push(
-        {
-          fileData: data,
-          template: template,
-          folder: folder
-        }
-      );
+      // Return the file
+      parent.children.push({
+        fileData: data,
+        template: template,
+        depth: parent.depth+1,
+        folder: folder
+      });
     }//if regexp pass or no regexp
   }// for i in files
 }
@@ -450,22 +470,43 @@ pmd.readFolder = function(objs, config, folder) {
  * @return objs array
  */
 pmd.generateData = function(config){
-  var objs = [];
+  var base = {
+    fileData: {
+      name: config.projectDispName,
+      isFolder: true
+    },
+    children: [
+
+    ]
+  };
+
   var indexData = [];
 
   config.folders.forEach(function(folder){
-    pmd.readFolder(objs, config, folder);
+    // Add the folder to the children
+    var fold = {
+      name: folder.name,
+      depth: 0,
+      children: []
+    };
+
+    pmd.readFolder(fold, config, folder);
+
+    // Add the folder to the children
+    base.children.push(fold);
   }); //config.folders.forEach
 
   // make the indexData available to all files
   // remove duplicates from indexData
-  objs.forEach(function(obj){
-    obj.fileData.files = indexData.filter(function(item, pos, ary) {
-                                            return !pos || item.name != ary[pos - 1].name;
-                                        });
+  base.children.forEach(function(obj){
+    if(obj.fileData) {
+      obj.fileData.files = indexData.filter(function(item, pos, ary) {
+        return !pos || item.name != ary[pos - 1].name;
+      });
+    }
   }); // objs.forEach
 
-  return objs;
+  return base;
 }//pmd.generateData
 
 
@@ -477,7 +518,14 @@ pmd.generateData = function(config){
  * @return Merged array
  */
 pmd.mergeObjs = function(objs){
-  objs.forEach(function(obj, i){
+  objs.children.forEach(function(obj, i){
+    // Check if the object has children
+    if(obj.children && obj.children.length > 0) {
+      obj = pmd.mergeObjs(obj);
+
+      return obj;
+    }
+
     //Seach for a matching element
     var
       data = obj.fileData,
@@ -486,11 +534,11 @@ pmd.mergeObjs = function(objs){
 
     // Loop over array but starting at next element
     for (var j = i+1; j < objs.length; j++){
-      if (objs[j].fileData.name === data.name) {
-        debug.log('Found matching entity:', objs[j].fileData.name);
-        relatedData = objs[j].fileData;
+      if (objs.children[j].fileData.name === data.name) {
+        debug.log('Found matching entity:', objs.children[j].fileData.name);
+        relatedData = objs.children[j].fileData;
         // Drop this entity as we'll merge it
-        objs.splice(j, 1);
+        objs.children.splice(j, 1);
         break;
       }// if
     }
@@ -522,7 +570,7 @@ pmd.mergeObjs = function(objs){
 
     }// relatedData
 
-    objs[i].fileData = data;
+    objs.children[i].fileData = data;
   }); //objs.forEach
 
   return objs;
@@ -536,20 +584,45 @@ pmd.mergeObjs = function(objs){
  */
 pmd.saveToFile = function(config, objs){
   // Finally print out data
-  objs.forEach(function(obj){
-	obj.fileData.files = pmd.globalFiles;
+  objs.files.forEach(function(obj){
+    if(obj && obj.fileData && !obj.fileData.isFolder) {
+      obj.fileData.folders = pmd.menuStructure.folders;
 
-    var markdown = obj.template(obj.fileData);
-    let docExtName = path.extname(obj.folder.template);
+      var markdown = obj.template(obj.fileData);
+      let docExtName = path.extname(obj.folder.template);
 
-    if (debug.debug){
-      debug.logFile(obj.fileData.name + docExtName, markdown);
-    }
+      if (debug.debug){
+        debug.logFile(obj.fileData.name + docExtName, markdown);
+      }
 
-    fs.writeFileSync(path.resolve(obj.folder.output.path,obj.fileData.name + docExtName), markdown);
+      // Register the list template
+      Handlebars.registerPartial( "list", fs.readFileSync(path.resolve(config.toc.menuTemplate),'utf8') );
+
+      fs.writeFileSync(path.resolve(obj.folder.output.path,obj.fileData.name + docExtName), markdown);
+    }
   });
 }//saveToFile
 
+pmd.menuToArray = function(parent, config, objs) {
+  objs.children.forEach(function(obj){
+    if(obj.children && obj.children.length > 0) {
+      parent.push(pmd.menuToArray(parent, config, obj));
+    }
+
+    if(obj.fileData) {
+      var file = {};
+      file.docFileName = obj.fileData.docFileName;
+      file.name = obj.fileData.name;
+      file.fileData = obj.fileData;
+      file.folder = obj.folder;
+      file.template = obj.template;
+      file.fileData.search = config.search;
+
+      parent.push(file);
+    }
+  })//objs.forEach
+}
+
 /**
  * Generates Table of Conents (TOC)
  *
@@ -564,6 +637,11 @@ pmd.generateToc = function(config, objs){
     debug.log('\nCreated TOC');
     var
       indexData = {
+        folders: objs.children,
+        projectDispName: config.projectDispName,
+        search: config.search
+      },
+      files = {
         files: [],
         projectDispName: config.projectDispName
       },
@@ -572,37 +650,34 @@ pmd.generateToc = function(config, objs){
       markdown
       ;
 
-    objs.forEach(function(obj){
-      var file = {};
-      let docExtName = path.extname(obj.folder.template);
-
-      file.docFileName = obj.fileData.name + docExtName;
-      file.name = obj.fileData.name;
-
-      indexData.files.push(file);
-    })//objs.forEach
+    // Parse the whole menu structure to a list of all files
+    pmd.menuToArray(files.files, config, objs);
 
     // Sort based on names
     // http://stackoverflow.com/questions/979256/sorting-an-array-of-javascript-objects
     // Remove duplicates from array, as array was already sorted
     // http://stackoverflow.com/questions/9229645/remove-duplicates-from-javascript-array
-    indexData.files.sort(function(a, b) {
+    files.files.sort(function(a, b) {
       return a.name.localeCompare(b.name);
     }).filter(function(item, pos, ary) {
-        return !pos || item != ary[pos - 1];
+      return !pos || item != ary[pos - 1];
     });
 
     templateContent = fs.readFileSync(path.resolve(config.toc.template),'utf8'),
-      template = Handlebars.compile(templateContent);
+        template = Handlebars.compile(templateContent);
+
+    // Register the list template
+    Handlebars.registerPartial( "list", fs.readFileSync(path.resolve(config.toc.menuTemplate),'utf8') );
+
     markdown = template(indexData);
 
-    pmd.globalFiles = indexData.files;
+    pmd.globalFiles = files;
+    pmd.menuStructure = indexData;
 
     fs.writeFileSync(path.resolve(config.folders[0].output.path, config.toc.fileName), markdown);
   }//config.templates.index
 }// generateToc
 
-
 module.exports = function(pDebug, pExtend){
   debug = pDebug;
   extend = pExtend;