generating the important docsets

matrix-hacks · Mar 13, 2017 · ff0477b · ff0477b
1 parent 3d44ce8
commit ff0477b
Show file tree

Hide file tree

Showing 4 changed files with 179 additions and 42 deletions.
diff --git a/bin/matrix-docset-gen b/bin/matrix-docset-gen
@@ -1,49 +1,25 @@
 #!/usr/bin/env node
-const fs = require('fs');
-const path = require('path');
-const { cd, mv, exec } = require('shelljs');
+const { PROJECTS, gen } = require('..');
 const args = require('minimist')(process.argv);
-const PROJECTS = {
-  'matrix-js-sdk': {
-    gitUrl: 'https://github.com/matrix-org/matrix-js-sdk',
-    docset: {
-      name: 'MatrixJSSDK',
-      icon: path.join(__dirname, '..', 'icon.png')
-    }
-  },
-  'matrix-appservice-bridge': {}
-}
-
-const project = PROJECTS[args.gen];
 
-if (!project) {
-  console.error(`Usage: matrix-docset-gen --project PROJECT`);
+const help = () => {
+  console.error(`Usage: matrix-docset-gen (--all | --project PROJECT) [--branch BRANCH]`);
   console.log(`Supported projects:\n\t`+Object.keys(PROJECTS).join('\n\t'));
   process.exit(1);
 }
 
-const { gitUrl, docset } = project;
-const basename = path.basename(gitUrl);
-const dir = path.resolve(path.join('projects', basename));
-const dest = path.resolve(path.join('docsets', basename));
-const tmpl = path.resolve(path.join('node_modules', 'jsdoc-dash-template'));
-const yarn = path.resolve(path.join('node_modules', '.bin', 'yarn'));
-const cfg = path.join(dir, 'docset-config.json');
-
-if (fs.existsSync(dir)){
-  cd(dir);
-  exec(`git pull origin master`);
+if (args.all) {
+  Object.keys(PROJECTS).map(p=>{
+    const project = PROJECTS[p];
+    gen(project, args.branch);
+  });
+} else if (args.gen) {
+  const project = PROJECTS[args.gen];
+  if (project) {
+    gen(project, args.branch);
+  } else {
+    help();
+  }
 } else {
-  exec(`git clone ${gitUrl} ${dir}`);
-  cd(dir);
+  help();
 }
-
-exec(yarn);
-fs.writeFileSync(cfg, JSON.stringify({ docset }));
-exec(`jsdoc -c ${cfg} -r lib -P package.json -R README.md -d ${dest} -t ${tmpl} --pedantic`);
-
-const { name, version } = require(path.join(dir, 'package'));
-const setroot = path.join(dest, `${docset.name}.docset`);
-const docroot = path.join(setroot, 'Contents', 'Resources', 'Documents');
-const entries = path.join(docroot, name, version, '*');
-mv(entries, docroot);
diff --git a/index.js b/index.js
@@ -0,0 +1,78 @@
+const fs = require('fs');
+const path = require('path');
+const { cd, mv, exec } = require('shelljs');
+const icon = path.join(__dirname, 'icon.png');
+
+module.exports.PROJECTS = {
+  'matrix-js-sdk': {
+    src: 'lib',
+    gitUrl: 'https://github.com/matrix-org/matrix-js-sdk',
+    defaultBranch: "develop",
+    docset: { icon, name: 'MatrixJSSDK' }
+  },
+  'matrix-appservice-bridge': {
+    src: 'lib',
+    gitUrl: 'https://github.com/matrix-org/matrix-appservice-bridge',
+    defaultBranch: "develop",
+    docset: { icon, name: 'MatrixAppserviceBridge' }
+  },
+  'matrix-appservice-node': {
+    src: 'lib',
+    gitUrl: 'https://github.com/matrix-org/matrix-appservice-node',
+    defaultBranch: "master",
+    docset: { icon, name: 'MatrixAppserviceNode' }
+  },
+  /* Looks like I didn't write code correctly for docset...
+   * Need to learn how to write JSDocs properly. Disable it for now.
+   *
+   * 'matrix-puppet-bridge': {
+   *   src: 'src',
+   *   gitUrl: 'https://github.com/matrix-hacks/matrix-puppet-bridge',
+   *   defaultBranch: "master",
+   *   docset: { icon, name: 'MatrixPuppetBridge' }
+   * }
+   */
+  /*
+   * The docset of this one seems quite bad, maybe due to all
+   * the transpilation or something... Just disable it.
+   *
+   *'matrix-react-sdk': {
+   *  gitUrl: 'https://github.com/matrix-org/matrix-react-sdk',
+   *  defaultBranch: "develop",
+   *  docset: { icon, name: 'MatrixReactSDK' }
+   *},
+   */
+}
+
+module.exports.gen = function gen(project, forceBranch) {
+  const { gitUrl, docset } = project;
+  const basename = path.basename(gitUrl);
+  const branch = forceBranch || project.defaultBranch || "master";
+  const dir = path.resolve(path.join(__dirname, 'projects', basename));
+  const dest = path.resolve(path.join(__dirname, 'docsets', basename));
+  const tmpl = path.resolve(path.join(__dirname, 'node_modules', 'jsdoc-dash-template'));
+  const yarn = path.resolve(path.join(__dirname, 'node_modules', '.bin', 'yarn'));
+  const jsdoc = path.resolve(path.join(__dirname, 'node_modules', '.bin', 'jsdoc'));
+  const cfg = path.join(dir, 'docset-config.json');
+
+  if (fs.existsSync(dir)){
+    cd(dir);
+    exec(`git reset --hard`);
+    exec(`git checkout ${branch}`);
+    exec(`git pull origin ${branch}`);
+  } else {
+    exec(`git clone ${gitUrl} ${dir}`);
+    cd(dir);
+    exec(`git checkout ${branch}`);
+  }
+
+  exec(yarn);
+  fs.writeFileSync(cfg, JSON.stringify({ docset }));
+  exec(`${jsdoc} -c ${cfg} -r ${project.src} -P package.json -R README.md -d ${dest} -t ${tmpl}`);
+
+  const { name, version } = require(path.join(dir, 'package'));
+  const setroot = path.join(dest, `${docset.name}.docset`);
+  const docroot = path.join(setroot, 'Contents', 'Resources', 'Documents');
+  const entries = path.join(docroot, name, version, '*');
+  mv(entries, docroot);
+}
diff --git a/package.json b/package.json
@@ -4,6 +4,7 @@
   "main": "index.js",
   "license": "MIT",
   "dependencies": {
+    "jsdoc": "^3.4.3",
     "jsdoc-dash-template": "^2.0.1",
     "minimist": "^1.2.0",
     "shelljs": "^0.7.7",

diff --git a/yarn.lock b/yarn.lock
@@ -6,6 +6,16 @@ abbrev@1:
   version "1.1.0"
   resolved "https://registry.yarnpkg.com/abbrev/-/abbrev-1.1.0.tgz#d0554c2256636e2f56e7c2e5ad183f859428d81f"
 
+acorn-jsx@^3.0.0:
+  version "3.0.1"
+  resolved "https://registry.yarnpkg.com/acorn-jsx/-/acorn-jsx-3.0.1.tgz#afdf9488fb1ecefc8348f6fb22f464e32a58b36b"
+  dependencies:
+    acorn "^3.0.4"
+
+acorn@^3.0.4, acorn@^3.3.0:
+  version "3.3.0"
+  resolved "https://registry.yarnpkg.com/acorn/-/acorn-3.3.0.tgz#45e37fb39e8da3f25baee3ff5369e2bb5f22017a"
+
 ajv@^4.9.1:
   version "4.11.5"
   resolved "https://registry.yarnpkg.com/ajv/-/ajv-4.11.5.tgz#b6ee74657b993a01dce44b7944d56f485828d5bd"
@@ -97,6 +107,10 @@ bluebird@^3.3.4, bluebird@^3.4.6:
   version "3.5.0"
   resolved "https://registry.yarnpkg.com/bluebird/-/bluebird-3.5.0.tgz#791420d7f551eea2897453a8a77653f96606d67c"
 
+bluebird@~3.4.6:
+  version "3.4.7"
+  resolved "https://registry.yarnpkg.com/bluebird/-/bluebird-3.4.7.tgz#f72d760be09b7f76d08ed8fae98b289a8d05fab3"
+
 [email protected]:
   version "2.10.1"
   resolved "https://registry.yarnpkg.com/boom/-/boom-2.10.1.tgz#39c8918ceff5799f83f9492a848f625add0c766f"
@@ -130,6 +144,12 @@ caseless@~0.12.0:
   version "0.12.0"
   resolved "https://registry.yarnpkg.com/caseless/-/caseless-0.12.0.tgz#1b681c21ff84033c826543090689420d187151dc"
 
+catharsis@~0.8.8:
+  version "0.8.8"
+  resolved "https://registry.yarnpkg.com/catharsis/-/catharsis-0.8.8.tgz#693479f43aac549d806bd73e924cd0d944951a06"
+  dependencies:
+    underscore-contrib "~0.3.0"
+
 chalk@^1.0.0, chalk@^1.1.1:
   version "1.1.3"
   resolved "https://registry.yarnpkg.com/chalk/-/chalk-1.1.3.tgz#a8115c55e4a702fe4d150abd3872822a7e09fc98"
@@ -294,10 +314,17 @@ end-of-stream@^1.0.0:
   dependencies:
     once "~1.3.0"
 
-escape-string-regexp@^1.0.2, escape-string-regexp@^1.0.5:
+escape-string-regexp@^1.0.2, escape-string-regexp@^1.0.5, escape-string-regexp@~1.0.5:
   version "1.0.5"
   resolved "https://registry.yarnpkg.com/escape-string-regexp/-/escape-string-regexp-1.0.5.tgz#1b61c0562190a8dff6ae3bb2cf0200ca130b86d4"
 
+espree@~3.1.7:
+  version "3.1.7"
+  resolved "https://registry.yarnpkg.com/espree/-/espree-3.1.7.tgz#fd5deec76a97a5120a9cd3a7cb1177a0923b11d2"
+  dependencies:
+    acorn "^3.3.0"
+    acorn-jsx "^3.0.0"
+
 extend@~3.0.0:
   version "3.0.0"
   resolved "https://registry.yarnpkg.com/extend/-/extend-3.0.0.tgz#5a474353b9f3353ddd8176dfd37b91c83a46f1d4"
@@ -397,7 +424,7 @@ [email protected]:
   version "2.0.3"
   resolved "https://registry.yarnpkg.com/graceful-fs/-/graceful-fs-2.0.3.tgz#7cd2cdb228a4a3f36e95efa6cc142de7d1a136d0"
 
-graceful-fs@^4.1.2:
+graceful-fs@^4.1.2, graceful-fs@^4.1.9:
   version "4.1.11"
   resolved "https://registry.yarnpkg.com/graceful-fs/-/graceful-fs-4.1.11.tgz#0e8bdfe4d1ddb8854d64e04ea7c00e2a026e5658"
 
@@ -550,6 +577,10 @@ js-tokens@^3.0.0:
   version "3.0.1"
   resolved "https://registry.yarnpkg.com/js-tokens/-/js-tokens-3.0.1.tgz#08e9f132484a2c45a30907e9dc4d5567b7f114d7"
 
+js2xmlparser@~1.0.0:
+  version "1.0.0"
+  resolved "https://registry.yarnpkg.com/js2xmlparser/-/js2xmlparser-1.0.0.tgz#5a170f2e8d6476ce45405e04823242513782fe30"
+
 jsbn@~0.1.0:
   version "0.1.1"
   resolved "https://registry.yarnpkg.com/jsbn/-/jsbn-0.1.1.tgz#a5e654c2e5a2deb5f201d96cefbca80c0ef2f513"
@@ -567,6 +598,23 @@ jsdoc-docset@^0.2.1:
     docset-generator "^0.2.1"
     object-assign "^4.0.1"
 
+jsdoc@^3.4.3:
+  version "3.4.3"
+  resolved "https://registry.yarnpkg.com/jsdoc/-/jsdoc-3.4.3.tgz#e5740d6145c681f6679e6c17783a88dbdd97ccd3"
+  dependencies:
+    bluebird "~3.4.6"
+    catharsis "~0.8.8"
+    escape-string-regexp "~1.0.5"
+    espree "~3.1.7"
+    js2xmlparser "~1.0.0"
+    klaw "~1.3.0"
+    marked "~0.3.6"
+    mkdirp "~0.5.1"
+    requizzle "~0.2.1"
+    strip-json-comments "~2.0.1"
+    taffydb "2.6.2"
+    underscore "~1.8.3"
+
 [email protected]:
   version "0.2.3"
   resolved "https://registry.yarnpkg.com/json-schema/-/json-schema-0.2.3.tgz#b480c892e59a2f05954ce727bd3f2a4e882f9e13"
@@ -593,6 +641,12 @@ jsprim@^1.2.2:
     json-schema "0.2.3"
     verror "1.3.6"
 
+klaw@~1.3.0:
+  version "1.3.1"
+  resolved "https://registry.yarnpkg.com/klaw/-/klaw-1.3.1.tgz#4088433b46b3b1ba259d78785d8e96f73ba02439"
+  optionalDependencies:
+    graceful-fs "^4.1.9"
+
 leven@^2.0.0:
   version "2.1.0"
   resolved "https://registry.yarnpkg.com/leven/-/leven-2.1.0.tgz#c2e7a9f772094dee9d34202ae8acce4687875580"
@@ -621,6 +675,10 @@ lru-cache@^4.0.1:
     pseudomap "^1.0.1"
     yallist "^2.0.0"
 
+marked@~0.3.6:
+  version "0.3.6"
+  resolved "https://registry.yarnpkg.com/marked/-/marked-0.3.6.tgz#b2c6c618fccece4ef86c4fc6cb8a7cbf5aeda8d7"
+
 mime-db@~1.26.0:
   version "1.26.0"
   resolved "https://registry.yarnpkg.com/mime-db/-/mime-db-1.26.0.tgz#eaffcd0e4fc6935cf8134da246e2e6c35305adff"
@@ -886,6 +944,12 @@ request@2, request@^2.75.0, request@^2.79.0:
     tunnel-agent "^0.6.0"
     uuid "^3.0.0"
 
+requizzle@~0.2.1:
+  version "0.2.1"
+  resolved "https://registry.yarnpkg.com/requizzle/-/requizzle-0.2.1.tgz#6943c3530c4d9a7e46f1cddd51c158fc670cdbde"
+  dependencies:
+    underscore "~1.6.0"
+
 resolve@^1.1.6:
   version "1.3.2"
   resolved "https://registry.yarnpkg.com/resolve/-/resolve-1.3.2.tgz#1f0442c9e0cbb8136e87b9305f932f46c7f28235"
@@ -1077,6 +1141,10 @@ supports-color@^2.0.0:
   version "2.0.0"
   resolved "https://registry.yarnpkg.com/supports-color/-/supports-color-2.0.0.tgz#535d045ce6b6363fa40117084629995e9df324c7"
 
+[email protected]:
+  version "2.6.2"
+  resolved "https://registry.yarnpkg.com/taffydb/-/taffydb-2.6.2.tgz#7cbcb64b5a141b6a2efc2c5d2c67b4e150b2a268"
+
 tar-pack@~3.3.0:
   version "3.3.0"
   resolved "https://registry.yarnpkg.com/tar-pack/-/tar-pack-3.3.0.tgz#30931816418f55afc4d21775afdd6720cee45dae"
@@ -1151,6 +1219,20 @@ uid-number@~0.0.6:
   version "0.0.6"
   resolved "https://registry.yarnpkg.com/uid-number/-/uid-number-0.0.6.tgz#0ea10e8035e8eb5b8e4449f06da1c730663baa81"
 
+underscore-contrib@~0.3.0:
+  version "0.3.0"
+  resolved "https://registry.yarnpkg.com/underscore-contrib/-/underscore-contrib-0.3.0.tgz#665b66c24783f8fa2b18c9f8cbb0e2c7d48c26c7"
+  dependencies:
+    underscore "1.6.0"
+
+[email protected], underscore@~1.6.0:
+  version "1.6.0"
+  resolved "https://registry.yarnpkg.com/underscore/-/underscore-1.6.0.tgz#8b38b10cacdef63337b8b24e4ff86d45aea529a8"
+
+underscore@~1.8.3:
+  version "1.8.3"
+  resolved "https://registry.yarnpkg.com/underscore/-/underscore-1.8.3.tgz#4f3fb53b106e6097fcf9cb4109f2a5e9bdfa5022"
+
 util-deprecate@~1.0.1:
   version "1.0.2"
   resolved "https://registry.yarnpkg.com/util-deprecate/-/util-deprecate-1.0.2.tgz#450d4dc9fa70de732762fbd2d4a28981419a0ccf"