feat(ci): added esdoc documentation generation, travis generation, auto deployment

hosted on https://github-issues-label-sync-package.superleap.xyz

closes #10

Author: 0-vortex

.gitignore

@@ -214,3 +214,4 @@ $RECYCLE.BIN/
 jsx/
 material-ui/
 svg/
+.publish/

.travis.yml

@@ -15,9 +15,11 @@ before_install:
   - npm i -g gulp
   - npm i -g bithound
 before_script:
+  - if (( "${TRAVIS_NODE_VERSION}" >= 6 )) && [ "$TRAVIS_BRANCH" = "master" ]; then export COVERAGE_REPORT=true; fi;
   - npm prune
 after_success:
   - npm run semantic-release
+  - npm run deploy
 branches:
   except:
     - /^v\d+\.\d+\.\d+$/

gulpfile.js

@@ -1,8 +1,16 @@
 "use strict";
+var paths = {
+    "pkg": "./package.json",
+    "docs": `./build/docs`
+};
+var fs = require('fs');
 var exec = require('child_process').exec;
 var path = require('path');
+var pkg = require('read-package-json');
 var gulp = require('gulp');
 var nsp = require('gulp-nsp');
+var esdoc = require("gulp-esdoc");
+var ghPages = require("gulp-gh-pages");
 
 gulp.task('nsp', function (cb) {
     nsp({package: path.resolve('package.json')}, cb);
@@ -19,4 +27,32 @@ gulp.task('bithound', function () {
     });
 });
 
+gulp.task('doc', function (cb) {
+    var config = {
+        "destination": paths.docs,
+        "title": "GitHub Issues Label Sync Module"
+    };
+
+    return gulp.src('./lib')
+        .pipe(esdoc(config));
+});
+
+gulp.task('predeploy', ['doc'], function () {
+    pkg(paths.pkg, console.log, true, function (error, data) {
+        var pkgName = data.name;
+        var pkgUser = data.repository.url.match(/github\.com\/([^\/]+)\//i)[1];
+
+        return fs.writeFile(`${paths.docs}/CNAME`, `${pkgName}-package.${pkgUser}.xyz`);
+    });
+});
+
+gulp.task('deploy', ['predeploy'], function () {
+    if (!process.env.COVERAGE_REPORT) {
+        return;
+    }
+
+    return gulp.src(`${paths.docs}/**/*`)
+        .pipe(ghPages());
+});
+
 gulp.task('prepublish', ['nsp', 'bithound']);

lib/LabelSync.js

@@ -1,7 +1,19 @@
 let GitHubApi = require("github");
 let Promise = require('bluebird');
 
-class GithubSync {
+/**
+ * Simple wrapper around the github module issues function
+ * @access public
+ */
+export default class GithubIssuesLabelSync {
+    /**
+     * The GitHub issue label model
+     * @typedef {Object} Label
+     * @property {String} Label.name - The name of the label
+     * @property {String} [Label.color] - The colour of the label
+     * @property {String} [Label.status] - Once a label operation is complete this field gets updated
+     */
+
     /**
      * In order to work as an NPM module this class has to be called with specific parameters
      * @example
@@ -22,173 +34,166 @@ class GithubSync {
      * };
      * let {user, repo, token, options} = config.github;
      * let labels = [];
-     * Array.from(JSON.parse(fs.readFileSync('./.issuesrc', 'utf8')).categories).forEach((category) => {
+     * array.from(JSON.parse(fs.readFileSync('./.issuesrc', 'utf8')).categories).forEach((category) => {
      *   category.labels.forEach((label) => {
      *     label.name = `${category.name}: ${label.name}`;
      *     labels.push(label);
      *   });
      * });
-     * let githubSync = new (require('./lib/GithubSync'))(options, user, repo, token);
-     * @param {Object} options - GitHubApi connect options
-     * @param {string} user - GitHub repository user
-     * @param {string} repo - GitHub repository name
-     * @param {string} token - GitHub personal access token
+     * let githubSync = new (require('./lib/LabelSync'))(options, user, repo, token);
+     * @param {Object} [options={}] - GitHubApi connect options
+     * @param {String} user - GitHub repository user
+     * @param {String} repo - GitHub repository name
+     * @param {String} token - GitHub personal access token
      */
     constructor(options = {}, user, repo, token) {
         this.options = options;
         this.user = user;
         this.repo = repo;
         this.token = token;
         this.github = new GitHubApi(this.options);
-        /**
-         * Async calls to this.getLabels() get logged here
-         * @type {Array}
-         */
-        this.labels = [];
-        /**
-         * Async calls to this.deleteLabels() get logged here
-         * @type {Array}
-         */
+        this._labels = [];
         this._deletedLabels = [];
-        /**
-         * Async calls to this.createLabels() get logged here
-         * @type {Array}
-         */
         this._createdLabels = [];
 
         this.authenticate();
     }
 
     /**
      * Get GitHubApi module connect options
-     * @returns {Object}
+     * @type {Object}
      */
     get options() {
         return this._options;
     }
 
     /**
      * Get GitHub repository username
-     * @returns {String}
+     * @type {String}
      */
     get user() {
         return this._user;
     }
 
     /**
      * Get GitHub repository name
-     * @returns {String}
+     * @type {String}
      */
     get repo() {
         return this._repo;
     }
 
     /**
      * Get GitHub repository token
-     * @returns {String}
+     * @type {String}
      */
     get token() {
         return this._token;
     }
 
     /**
      * Get GitHubApi module
-     * @returns {GitHubApi|module.exports}
+     * @link github/Client
+     * @type {github/Client|module.exports}
      */
     get github() {
         return this._github;
     }
 
     /**
      * Get GitHub repository labels
-     * @returns {Array}
+     * @type {Array<GithubIssuesLabelSync.Label>}
      */
     get labels() {
         return this._labels;
     }
 
     /**
      * Get GitHubApi repository deleted labels
-     * @returns {Array}
+     * @type {Array<GithubIssuesLabelSync.Label>}
      */
     get deletedLabels() {
         return this._deletedLabels;
     }
 
     /**
      * Get GitHubApi repository created labels
-     * @returns {Array}
+     * @type {Array<GithubIssuesLabelSync.Label>}
      */
     get createdLabels() {
         return this._createdLabels;
     }
 
     /**
      * Set GitHubApi module connect options
-     * @param {Object} object
+     * @type {Object}
+     * @property {Boolean} [options.debug=false] - Get request information with each call
+     * @property {Boolean} [options.followRedirects=false] - We don't need this for issues
+     * @property {Promise} Promise - We are using bluebird promises peering with github api package
      */
     set options(object) {
         this._options = object;
     }
 
     /**
      * Set GitHubApi repository username
-     * @param {String} repoUrlUser
+     * @type {String}
      */
     set user(repoUrlUser) {
         this._user = repoUrlUser;
     }
 
     /**
      * Set GitHubApi repository name
-     * @param {String} repoUrlName
+     * @type {String}
      */
     set repo(repoUrlName) {
         this._repo = repoUrlName;
     }
 
     /**
      * Set GitHubApi OAuth2 personal access token
-     * @param {String} personalAccessToken
+     * @type {String}
      */
     set token(personalAccessToken) {
         this._token = personalAccessToken;
     }
 
     /**
      * Set GitHubApi Client
-     * @param {GitHubApi|module.exports} Client
+     * @type {github/Client|module.exports}
      */
     set github(Client) {
         this._github = Client;
     }
 
     /**
      * Set GitHubApi repository labels
-     * @param {Array} labels
+     * @type {Array<GithubIssuesLabelSync.Label>}
      */
     set labels(labels) {
         this._labels = labels;
     }
 
     /**
      * Push GitHubApi repository deleted label
-     * @param {Object} label
+     * @type {GithubIssuesLabelSync.Label}
      */
     set deletedLabel(label) {
         this._deletedLabels.push(label);
     }
 
     /**
      * Push GitHubApi repository created label
-     * @param {Object} label
+     * @type {GithubIssuesLabelSync.Label}
      */
     set createdLabel(label) {
         this._createdLabels.push(label);
     }
 
     /**
      * We only do this once
+     * @access private
      */
     authenticate() {
         this.github.authenticate({
@@ -205,7 +210,7 @@ class GithubSync {
      *   console.log(response);
      * });
      * @async
-     * @param {Boolean} meta
+     * @param {Boolean} [meta=false] - Get extended response information
      * @returns {Promise}
      */
     getLabels(meta = false) {
@@ -233,7 +238,8 @@ class GithubSync {
      *   console.log(githubSync.createdLabels);
      * });
      * @async
-     * @param {Object} label
+     * @param {GithubIssuesLabelSync.Label} label - The label we want to delete
+     * @param {String} label.name - The label's name
      * @returns {Promise}
      */
     deleteLabel(label) {
@@ -266,7 +272,7 @@ class GithubSync {
      *   console.log(githubSync.deletedLabels);
      * });
      * @async
-     * @param {Array} labels
+     * @param {Array<GithubIssuesLabelSync.Label>} labels - The labels we want to delete
      * @returns {Promise}
      */
     deleteLabels(labels) {
@@ -285,7 +291,10 @@ class GithubSync {
      *   console.log(githubSync.createdLabels);
      * });
      * @async
-     * @param {Object} label
+     * @param {GithubIssuesLabelSync.Label} label - The label we want to create
+     * @param {String} label.name - The label's name
+     * @param {String} label.color - The label's colour
+     * @param {String} label.status - Promise status of operation
      * @returns {Promise}
      */
     createLabel(label) {
@@ -324,7 +333,7 @@ class GithubSync {
      *   console.log(githubSync.createdLabels);
      * });
      * @async
-     * @param {Array} labels
+     * @param {Array<GithubIssuesLabelSync.Label>} labels - The labels we want to create
      * @returns {Promise}
      */
     createLabels(labels) {
@@ -363,8 +372,8 @@ class GithubSync {
      *   console.log(githubSync.createdLabels);
      * });
      * @async
-     * @param {Array} labels
-     * @param {Boolean} purge
+     * @param {Array<GithubIssuesLabelSync.Label>} labels - The labels we want to import
+     * @param {Boolean} [purge=false] - Wether to delete all existing tags on remote or not
      * @returns {Promise}
      */
     importLabels(labels, purge = true) {
@@ -373,5 +382,3 @@ class GithubSync {
         });
     }
 }
-
-module.exports = GithubSync;

package.json

@@ -7,6 +7,7 @@
   },
   "scripts": {
     "test": "",
+    "deploy": "gulp deploy",
     "prepublish": "gulp prepublish",
     "semantic-release": "semantic-release pre && npm publish && semantic-release post"
   },
@@ -38,16 +39,20 @@
     "bithound": "^1.3.0",
     "commitizen": "^2.8.2",
     "cz-conventional-changelog": "^1.1.6",
+    "esdoc": "^0.4.7",
     "gulp": "^3.9.1",
     "gulp-codecov": "^2.0.2",
+    "gulp-esdoc": "^0.2.0",
     "gulp-eslint": "^3.0.1",
     "gulp-exclude-gitignore": "^1.0.0",
+    "gulp-gh-pages": "^0.5.4",
     "gulp-istanbul": "^1.0.0",
     "gulp-mocha": "^2.2.0",
     "gulp-nsp": "^2.4.1",
     "gulp-plumber": "^1.1.0",
     "mocha": "^2.5.3",
     "nsp": "^2.5.0",
+    "read-package-json": "^2.0.4",
     "semantic-release": "^6.3.0"
   },
   "config": {