Merge pull request #1 from cybercoder/develop

Develop

Author: Vahid Alimohamadi

.eslintrc.json

@@ -1,7 +1,6 @@
 {
     "extends": "standard",
     "env": {
-      "browser": true,
       "node": true,
       "mocha": true
     },

.gitignore

@@ -1 +1,11 @@
-node_modules
+node_modules
+.idea
+dump.rdb
+.DS_Store
+.vscode
+yarn-error.log
+build
+dist
+doc
+docs
+public

README.MD

@@ -0,0 +1,71 @@
+# socketio-doc
+A socket.io document generator.
+
+## Installation and Usage
+You can install ```socketio-doc``` globally or in your project's ```node_modules``` folder.
+
+To install the latest version on npm globally:
+
+```
+npm install -g socketio-doc
+```
+
+To install the latest version on npm locally and save it in your package's ```package.json``` file:
+
+```
+npm install --save-dev socketio-doc
+```
+
+## Configuration
+By default needs a file named ```socketio-doc.conf.json``` in your project root folder with contents like these:
+
+```
+{
+  "version" : "2.3.1",
+  "source": ["./src/io/*.js"],
+  "destination" : "./socketio-doc"
+}
+```
+or you can simply pass custom file: ```socketio-doc -c <filename>```.
+
+## Inline comments
+This is a example for commenting ```emits```, and ```listens```:
+
+```
+    /**
+     * Singleline or multiline description text. Line breaks are preserved.
+     * @socket.io-doc
+     * @listen exampleListen description
+     * @tag Messaging
+     * @data {object}
+     * @example
+     * {
+     *   "id": 1,
+     *   "title": 5
+     * }
+     */
+    socket.on('exampleListen', data => {
+      /**
+       * Singleline or multiline description text. Line breaks are preserved.
+       * @socket.io-doc
+       * @emit exampleEmit description
+       * @tag Messaging
+       * @data {object}
+       * @example { id: 5, data: [2, 3] }
+       */
+      socket.emit('exampleEmit', { id: 5, data: [2, 3] });
+    });
+```
+
+to generate document in interactive ```HTML```, just try:
+
+```
+socketio-doc
+```
+if it is installed globally
+or
+```
+./node_modules/.bin/socketio-doc
+```
+if installed locally.
+It will genetate folders which determined in configuration file as destination.

cli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('./index')

index.js

@@ -1,27 +1,72 @@
-const commentParser = require('comment-parser');
-
-const parseFile = file => new Promise((resolve,reject)=>{
-    commentParser.file(file, (err,result)=>err ? reject(err) : resolve(result));
-})
-
-parseFile('./sample.js').then(c=> {
-    let all = Object.values(c).reduce((result,item)=>{
-        if (!item.tags.some(i=>i.tag==='socket.io-doc')) return result;
-        let category = item.tags.find(i=>i.tag==='tag');
-        category=category ? category.name : 'uncategorized';
-
-        let transformed = item.tags.reduce((r,t)=>{
-            (t.tag === 'listen' || t.tag ==='emit') && (r={...r,action:t.tag, event: t.name});
-            t.tag==='example' && (r={...r, example: t.name.replace(/\n|\r/g, "")+t.description.replace(/\n|\r/g, "")});
-            return r;
-        },{
-            category,
-            description:item.description || null
-        });
-        result.push(transformed);
-        return result;
-    },[]);
-
-    console.log(all);
-}).catch(e=>console.error(e));
+#!/usr/bin/env node
+const {get_files, parse_file, createLinks, generate_html_template} = require('./lib');
+const fs = require('fs');
+const path = require('path');
 
+const socketioDocCli =  require("commander");
+const chalk =  require("chalk");
+
+socketioDocCli.option('-c, --config <string>', 'Specify config path.').action( cmd=> {
+    let {config} = cmd;
+    console.log(chalk.white("\n\tconfig file: "), chalk.gray(config || 'config file not specified, using default.','\n'));
+
+    // check config file flag or default config file existance.
+    if (!config && !fs.existsSync(path.resolve('./socketio-doc.conf.json'))) {
+        return console.log(chalk.red('config file not found.\n'));
+    }
+
+    if (config && !fs.existsSync(path.resolve(config))) {
+        return console.log(chalk.red('specified config file, not found.\n'));
+    }
+
+    let { source, destination, version } = config ? require(path.resolve(`${config}`)) : require(path.resolve('./socketio-doc.conf.json'));
+
+    destination = path.resolve(destination);
+
+    if (!source) {
+        return console.log(chalk.red('source not determined.\n'));
+    }
+
+    if (!destination) {
+        return console.log(chalk.red('destination not determined.\n'));
+    }
+
+    console.log(chalk.green("Start creating documents...\n"));
+
+    return get_files(source)
+    .then(async files=>{
+        let results = await Promise.all(files.flat().map(async file=> {
+            let c = await parse_file(file);
+            return Object.values(c).reduce((result,item)=>{
+                if (!item.tags.some(i=>i.tag==='socket.io-doc')) return result;
+                let tag = item.tags.find(i=>i.tag==='tag');
+                tag=tag ? tag.name : 'uncategorized';
+            
+                let transformed = item.tags.reduce((r,t)=>{
+                    (t.tag === 'listen' || t.tag ==='emit') && (r={...r,action:t.tag, event: t.name});
+                    t.tag==='example' && (r={...r, example: t.name.replace(/\n|\r/g, "")+t.description.replace(/\n|\r/g, "")});
+                    return r;
+                },{
+                    tag,
+                    description:item.description || null
+                });
+                result.push(transformed);
+                return result;
+            },[]);
+        }));
+    
+        results=results.flat();
+
+        let emitLinks = createLinks(results.filter(r=>r.action==='listen'));
+
+        !fs.existsSync(`${destination}`) && fs.mkdirSync(`${destination}`);
+        !fs.existsSync(`${destination}/css`) && fs.mkdirSync(`${destination}/css`);
+
+        fs.createReadStream(`${__dirname}/templates/default/css/style.css`).pipe(fs.createWriteStream(`${destination}/css/style.css`));
+        fs.writeFileSync(`${destination}/index.html`, generate_html_template(emitLinks,results,version));
+        console.log(chalk.green(`\tBuild compelete :  ${destination}`))
+    })
+    .catch(e=>console.error(chalk.red(e)));
+   });
+
+   socketioDocCli.parse(process.argv);