docs: refactoring doc scripts (#1743)

.github/CONTRIBUTING.md

@@ -172,6 +172,35 @@ Checklist:
   - [ ] I made sure all breaking changes are noted
   - [x] I'm not going to say "nifty" anymore
 
+### Updating Documentation
+
+All of the documentation is powered by JSDoc, we parse it into JSON and feed it to an [application](https://github.com/GoogleCloudPlatform/gcloud-common/tree/master/site) built in Angular. Hopefully our CI builds and updates the documentation for each successful merge to master, but if for whatever reason a manual update is required please refer to the following steps.
+
+We can build the documentation using the `npm run prepare-ghpages` command. This command optionally accepts two parameters.
+
+* module - The name of the module to build (e.g. `google-cloud`).
+* version - The target version of the module. (e.g. `0.43.0`) Defaults to master.
+
+If both parameters are omitted, we will build the master docs for all modules.
+
+```sh
+$ npm run prepare-ghpages google-cloud 0.43.0
+```
+
+Now it's time to push the docs! If you wish to preview locally you can optionally run an http server in the `gh-pages` folder.
+
+```sh
+$ cd gh-pages
+$ http-server . # Run the server to look for any visual errors
+$ git push origin gh-pages
+$ cd ..
+```
+Finally the last thing to do is cleanup the submodule we created to copy over the JSON.
+
+```sh
+$ npm run remove-ghpages
+```
+
 [elsewhere]: ../README.md#elsewhere
 [gcloudcli]: https://developers.google.com/cloud/sdk/gcloud/
 [indvcla]: https://developers.google.com/open-source/cla/individual

.gitignore

@@ -4,5 +4,5 @@ packages/*/CONTRIBUTORS
 packages/*/COPYING
 **/node_modules
 **/coverage/*
-docs/json/**/*.json
+docs/json
 *.log

.jshintrc

@@ -29,6 +29,7 @@
     "echo": true,
     "exit": true,
     "cd": true,
-    "mkdir": true
+    "mkdir": true,
+    "test": true
   }
 }

.travis.yml

@@ -21,7 +21,26 @@ before_script:
     fi
 script: "node ./scripts/build.js"
 after_success:
-  - if [ $IS_PUSH_TO_MASTER ]; then
-      node ./scripts/build-docs.js;
+  # We check to see if the job number ends with 1 (e.g. 234234.1)
+  # letting us know it is the first pass for this build
+  - if [ $IS_PUSH_TO_MASTER && "${TRAVIS_JOB_NUMBER}" == *1 ]; then
+      rm -rf docs/json;
+      npm run docs;
+      git submodule add -q -b gh-pages https://${GH_OAUTH_TOKEN}@github.com/${GH_OWNER}/${GH_PROJECT_NAME} ghpages;
+      cp -rf docs/json/* ghpages/json;
+      cp docs/manifest.json ghpages;
+      cd ghpages;
+      set +e;
+      git add .;
+      set -e;
+      if [[ -z "$(git status --porcelain)" ]]; then
+        echo "Nothing to commit. Exiting without pushing changes.";
+        exit 0;
+      fi;
+      git config user.name "travis-ci";
+      git config user.email "travis@travis-ci.org";
+      git commit -m "Update docs for ${TRAVIS_TAG:-master} [ci skip]";
+      git status;
+      git push -q https://${GH_OAUTH_TOKEN}@github.com/${GH_OWNER}/${GH_PROJECT_NAME} HEAD:gh-pages;
     fi
 sudo: false

docs/manifest.json

@@ -13,6 +13,7 @@
       "name": "google-cloud",
       "defaultService": "google-cloud",
       "versions": [
+        "0.43.0",
         "0.42.2",
         "0.41.2",
         "0.41.0",
@@ -132,6 +133,7 @@
       "name": "@google-cloud/language",
       "defaultService": "language",
       "versions": [
+        "0.5.0",
         "0.4.0",
         "0.3.0",
         "0.2.0",
@@ -145,13 +147,23 @@
       "name": "@google-cloud/logging",
       "defaultService": "logging",
       "versions": [
+        "0.5.0",
         "0.4.0",
         "0.3.0",
         "0.2.0",
         "0.1.1",
         "master"
       ]
     },
+    {
+      "id": "monitoring",
+      "name": "@google-cloud/monitoring",
+      "defaultService": "monitoring",
+      "versions": [
+        "0.1.1",
+        "master"
+      ]
+    },
     {
       "id": "prediction",
       "name": "@google-cloud/prediction",
@@ -169,6 +181,7 @@
       "name": "@google-cloud/pubsub",
       "defaultService": "pubsub",
       "versions": [
+        "0.5.0",
         "0.4.0",
         "0.3.0",
         "0.2.0",
@@ -192,6 +205,7 @@
       "name": "@google-cloud/speech",
       "defaultService": "speech",
       "versions": [
+        "0.4.0",
         "0.3.0",
         "0.2.0",
         "master"
@@ -202,6 +216,7 @@
       "name": "@google-cloud/storage",
       "defaultService": "storage",
       "versions": [
+        "0.4.0",
         "0.3.0",
         "0.2.0",
         "0.1.1",
@@ -225,6 +240,7 @@
       "name": "@google-cloud/vision",
       "defaultService": "vision",
       "versions": [
+        "0.5.0",
         "0.4.0",
         "0.3.0",
         "0.2.0",
@@ -237,4 +253,4 @@
     "title": "npm",
     "href": "https://www.npmjs.com/package/gcloud"
   }
-}
+}

package.json

@@ -34,8 +34,9 @@
     "postinstall": "node ./scripts/install.js",
     "link-common": "node ./scripts/link-common.js",
     "update-deps": "node ./scripts/update-deps.js",
-    "docs": "node ./scripts/docs/packages.js",
-    "bundle": "node ./scripts/docs/bundle.js",
+    "docs": "node ./scripts/docs",
+    "prepare-ghpages": "node ./scripts/docs/prepare.js",
+    "remove-ghpages": "node ./scripts/docs/remove.js",
     "lint": "jshint scripts/ packages/ system-test/ test/ && jscs packages/ system-test/ test/",
     "test": "npm run docs && npm run snippet-test && npm run unit-test",
     "unit-test": "mocha --timeout 5000 --bail packages/*/test/*.js",