docs: add process to build docs

command to extract and generate .md/.html files in docs/
automated way to update gh-pages branch when the docs change

command to extract and generate .md/.html files in docs/

#127 - npm run docs will build the HTML + Markdown. 💃

automated way to update gh-pages branch when the docs change

Let's talk about this one :) It sounds nice to be able to accept a PR of source code changes, and have the docs generated. This is actually pretty doable, but with side effects.

If someone changes source code, sends a PR, the tests pass, and we merge it, we would want to

run npm docs to generate the docs directory,
commit the new files,
push the changes to master, and
push docs/html (the generated jsdoc directory) to gh-pages.

This doesn't feel too great, since we're letting a robot create a commit and push to master!

Travis will do whatever we say every time a PR is sent, and every time a commit is merged into master. It doesn't seem that we can do different things from different triggers. So, if someone changes source code, sends in a PR, the tests pass, but we don't merge it... Uh oh! Travis just kept on running, generated the docs, and pushed to master & gh-pages.

#127 currently has Travis push the docs/html folder from master into gh-pages after every successful PR-triggered Travis build & push to master. This is safer since even though it's running on every PR that passes the tests, it's using master as its source of truth.

So, that's the state of the task now. If you have any ideas for workarounds or know of other solutions, let me know.

Sorry, I made a great job in being unclear on the second point, what I meant was pushing the docs after a merge into master that affects the docs, which is what you did :)

We might move the docs step from Travis to the CI that we use to run the build that includes the regression tests, but this looks very good for now, thanks! Going through all the PRs now.

Can we use PRs here too? i.e. A script will detect that docs are behind master (or latest tag), build docs, and auto create PR for updated docs. We then merge the PR manually. I prefer latest tag so we don't spam the PR/issues list & our inboxes. Thoughts?

Off-topic: Similar approach could be used for google/google-api-nodejs-client regeneration of APIs.

I'm not sure we want an additional PR.
JSDoc changes would be reviewed in the PR that affects them, and new docs generated when needed (when we merge into master or when we tag a new release).