Documentation Index and subdirectories parsing

.gitignore

@@ -7,6 +7,7 @@ lib-cov
 *.pid
 *.gz
 
+
 pids
 logs
 output
@@ -39,4 +40,4 @@ ehthumbs.db
 Desktop.ini
 
 # Recycle Bin used on file shares
-$RECYCLE.BIN/
+$RECYCLE.BIN/

README.md

@@ -4,6 +4,31 @@ jsdox is a simple jsdoc 3 generator.  It pulls documentation tags based on a sub
 
 Relies on the [JSDoc3 parser](https://github.com/mrjoelkemp/jsdoc3-parser) to get the full AST including comments.
 
+### CLI Options
+
+Usage: `jsdox [options] <file | directory>`
+
+`--config <file>` (alias `-c`): Configuration JSON file.
+
+`--All` (alias `-A`): Generates documentation for all available elements including internal methods.
+
+`--debug` (alias `-d`): Prints debugging information to the console.
+
+`--help` (alias `-H`): Prints help and quits.
+
+`--version` (alias `-v`): Prints the current version and quits.
+
+`--output` (alias `-o`): Output directory. Default value is 'output'.
+
+`--templateDir` (alias `-t`): Template directory to use instead of built-in ones.
+
+`--index` (alias `-i`): Generates an index with the documentation. A file name can be provided in argument. Default value is 'index'.
+
+`--recursive` (alias `-r`): Generates documentation in all subdirectories of the source folder.
+
+`--respect-recursive` (alias `--rr`): Generate subdirectories and copy the original organization of the sources.
+
+
 # Resources
 * [jsdox](http://jsdox.org) Documentation
 * Github [repo](https://github.com/sutoiku/jsdox)

jsdox.js

@@ -44,11 +44,24 @@ var
     .options('templateDir', {
       alias: 't'
     })
+    .options('index', {
+     alias: 'i'
+    })
+    .options('recursive',{
+     alias: 'r'
+    })
+    .options('respect-recursive', {
+     alias: 'rr'
+    })
     .argv,
   packageJson = require('./package.json'),
   jsdocParser = require('jsdoc3-parser'),
   analyze = require('./lib/analyze'),
-  generateMD = require('./lib/generateMD');
+  generateMD = require('./lib/generateMD'),
+  index= {
+    classes: [],
+    functions: []
+  };
 
 function inspect(text) {
   return util.inspect(text, false, 20);
@@ -58,13 +71,17 @@ function printHelp(){
   console.log('Usage:\tjsdox [options] <file | directory>');
   console.log('\tjsdox --All --output docs folder\n');
   console.log('Options:');
-  console.log('  -c, --config \t<file>\t Configuration JSON file.');
-  console.log('  -A, --All\t\t Generates documentation for all available elements including internal methods.');
-  console.log('  -d, --debug\t\t Prints debugging information to the console.');
-  console.log('  -H, --help\t\t Prints this message and quits.');
-  console.log('  -v, --version\t\t Prints the current version and quits.');
-  console.log('  -o, --output\t\t Output directory.');
-  console.log('  -t, --templateDir\t Template directory to use instead of built-in ones.');
+  console.log('  -c,\t--config \t<file>\t Configuration JSON file.');
+  console.log('  -A,\t--All\t\t\t Generates documentation for all available elements including internal methods.');
+  console.log('  -d,\t--debug\t\t\t Prints debugging information to the console.');
+  console.log('  -H,\t--help\t\t\t Prints this message and quits.');
+  console.log('  -v,\t--version\t\t Prints the current version and quits.');
+  console.log('  -o,\t--output\t\t Output directory.');
+  console.log('  -t,\t--templateDir\t\t Template directory to use instead of built-in ones.');
+  console.log('  -i,\t--index\t\t\t Generates an index with the documentation. A file name can be provided in argument.');
+  console.log('  -r,\t--recursive\t\t Generates documentation in all subdirectories of the directory given as argument.');
+  console.log('  --rr,\t--respect-recursive\t Will generate subdirectories and copy the original organization of the sources.');
+
   process.exit();
 }
 
@@ -85,8 +102,27 @@ function generateForDir(filename, destination, templateDir, cb, fileCb) {
       touched = 0,
       error = null;
 
+  var readdirSyncRec = function(dir, filelist) {
+    var files = fs.readdirSync(dir);
+    filelist = filelist || [];
+    files.forEach(function(file) {
+      if (fs.statSync(path.join(dir,file)).isDirectory()) {
+        filelist = readdirSyncRec(path.join(dir,file), filelist);
+      }
+      else {
+        filelist.push(path.join(dir,file));
+      }
+    });
+    return filelist;
+  };
+
   function oneFile(directory, file, cb) {
-    var fullpath = path.join(destination, file);
+    var fullpath;
+    if(argv.rr) {
+      fullpath = path.join(path.join(destination, path.dirname(file)), path.basename(file));
+    }else{
+      fullpath = path.join(destination, file);
+    }
     fullpath = fullpath.replace(/\.js$/, '.md');
 
     if (argv.debug) {
@@ -95,7 +131,7 @@ function generateForDir(filename, destination, templateDir, cb, fileCb) {
 
     waiting++;
 
-    jsdocParser(path.join(directory, file), function(err, result) {
+    jsdocParser(path.join(directory, path.basename(file)), function(err, result) {
       if (err) {
         console.error('Error generating docs for file', file, err);
         waiting--;
@@ -114,6 +150,28 @@ function generateForDir(filename, destination, templateDir, cb, fileCb) {
       var data = analyze(result, argv),
           output = generateMD(data, templateDir);
 
+
+      if(argv.index) {
+        for (var i = 0; i < data.functions.length; i++) {
+          if (data.functions[i].className === undefined) {
+            var toAddFct = data.functions[i];
+            toAddFct.file = path.relative(destination,fullpath);
+            toAddFct.sourcePath = path.relative(destination,path.join(directory,path.basename(file)));
+            index.functions.push(toAddFct);
+          }
+        }
+        for (var j = 0; j < data.classes.length; j++) {
+          if (data.functions[j].className === undefined) {
+            var toAddClass = data.classes[j];
+            toAddClass.file = path.relative(destination,fullpath);
+            toAddClass.sourcePath = path.relative(destination,path.join(directory,path.basename(file)));
+            index.classes.push(toAddClass);
+          }
+        }
+      }
+
+
+
       if (output) {
         fileCb && fileCb(file, data);
         fs.writeFile(fullpath, output, function(err) {
@@ -140,26 +198,64 @@ function generateForDir(filename, destination, templateDir, cb, fileCb) {
     oneFile(path.dirname(filename), path.basename(filename), cb);
 
   } else {
-    fs.stat(filename, function (err, s) {
-      if (!err && s.isDirectory()) {
-        fs.readdir(filename, function(err, files) {
-          if (err) {
-            console.error('Error generating docs for files', filename, err);
-            return cb(err);
-          }
-          files.forEach(function(file) {
-            if (file.match(/\.js$/)) {
-              oneFile(filename, file, cb), touched++;
+    if(argv.recursive || argv.rr){
+      fs.stat(filename, function (err, s) {
+        if (!err && s.isDirectory()) {
+          var contentList=readdirSyncRec(filename);
+          contentList.forEach(function(fileFullPath) {
+            if(argv.rr){
+              //create the sub-directories
+              try{
+                fs.mkdirSync(path.join(destination,path.dirname(fileFullPath)));
+              }catch(err){} //lazy way: if the file already exists, everything is alright.
+              try {
+                oneFile(path.dirname(fileFullPath), fileFullPath, cb), touched++;
+              }catch(err){
+                console.error('Error generating docs for files', path.basename(fileFullPath), err);
+                return cb(err);
+              }
+            }else {
+              try{
+                oneFile(path.dirname(fileFullPath), path.basename(fileFullPath), cb), touched++;
+              }catch(err){
+                console.error('Error generating docs for files', path.basename(fileFullPath), err);
+                return cb(err);
+              }
             }
+
+
           });
           if(!touched) {
             cb();
           }
-        });
-      } else {
-        cb();
-      }
-    });
+
+        } else {
+          cb();
+        }
+      });
+    }else {
+      fs.stat(filename, function (err, s) {
+        if (!err && s.isDirectory()) {
+          fs.readdir(filename, function (err, files) {
+            if (err) {
+              console.error('Error generating docs for files', filename, err);
+              return cb(err);
+            }
+            files.forEach(function (file) {
+              if (file.match(/\.js$/)) {
+                oneFile(filename, file, cb), touched++;
+              }
+            });
+            if (!touched) {
+              cb();
+            }
+          });
+        } else {
+          cb();
+        }
+      });
+    }
+
   }
 }
 
@@ -214,9 +310,29 @@ function main(){
 
         return deferred.promise;
       }))
-      .then(function () {
-        console.log('jsdox completed');
-      });
+        .then(function(){
+          //create index
+          if(argv.index) {
+            var fileName;
+            if(argv.index===true){
+              fileName='index';
+            }else{
+              fileName=argv.index;
+            }
+            if(typeof argv.output === 'string'){
+              fileName=path.join(argv.output,fileName);
+            }else{
+              fileName=path.join('output',fileName);
+            }
+            fs.writeFileSync(fileName+'.md', generateMD(index, argv.templateDir, true));
+          }
+
+
+
+        })
+        .then(function () {
+          console.log('jsdox completed');
+        });
     });
   } else {
     console.error('Error missing input file or directory.');

lib/generateMD.js

@@ -8,20 +8,49 @@ var Mustache = require('mustache'),
  * @param  {String} templateDir - templates directory (optional)
  * @return {String} Markdown output
  */
-module.exports = function(ast, templateDir) {
+module.exports = function(ast, templateDir, isIndex) {
   if (!ast) { throw new Error('no analyzed ast to generate markdown from'); }
 
+  var templates;
+
   if (!templateDir) {
     templateDir = path.resolve(__dirname, '../templates');
   } else {
     templateDir = templateDir.replace(/\\/g, '/');
   }
 
-  var templates = {
-    file: fs.readFileSync(templateDir + '/file.mustache', 'utf8'),
-    class: fs.readFileSync(templateDir + '/class.mustache', 'utf8'),
-    function: fs.readFileSync(templateDir + '/function.mustache', 'utf8')
-  };
+  //if ast is an index file, we need to sort the contents and to use the right templates;
+  if(isIndex){
+    console.log('Now generating index');
+    ast.classes.sort(function(a,b){
+      if(a.name< b.name){
+        return -1;
+      }else{
+        return 1;
+      }
+    });
+    ast.functions.sort(function(a,b){
+      if(a.name< b.name){
+        return -1;
+      }else{
+        return 1;
+      }
+    });
+
+    templates = {
+      index: fs.readFileSync(templateDir + '/index.mustache', 'utf8'),
+      class: fs.readFileSync(templateDir + '/overview.mustache', 'utf8'),//do we need different overview templates for functions or classes here ?
+      function: fs.readFileSync(templateDir + '/overview.mustache', 'utf8')
+    };
+    return Mustache.render(templates.index, ast, templates);;
+  }else {
 
-  return Mustache.render(templates.file, ast, templates);
+
+    templates = {
+      file: fs.readFileSync(templateDir + '/file.mustache', 'utf8'),
+      class: fs.readFileSync(templateDir + '/class.mustache', 'utf8'),
+      function: fs.readFileSync(templateDir + '/function.mustache', 'utf8')
+    };
+    return Mustache.render(templates.file, ast, templates);
+  }
 }