Build infrastructure for live examples in documentation

[kadamwhite]

@mzgoddard Running into some trouble here. I would think that running grunt docs-dev would keep the webpack server running; but it just completes once, and then exits. Any insight on what I might be doing wrong?

Steps to reproduce: pull this branch, run grunt docs-dev; observe that example files are generated, but that jekyll does not run.

Additionally I am not clear on how to get the rendered JS to be minified and compressed (we can't use the -p webpack CLI option from grunt), and I would like to build minified versions to maintain the performance of the docs site.

[kadamwhite]

Update: npm run build now also builds examples; if the examples are built this way (also accessible by running grunt webpack:docs-examples), then the examples work.

If the examples are built using grunt webpack:docs-examples-dev, which should be very similar, I get this error:

index.js:51Uncaught Error: locals[0] does not appear to be a module object with Hot Module replacement API enabled. You should disable react-transform-hmr in production by using env section in Babel configuration. See the example in README: https://github.com/gaearon/react-transform-hmr

@mzgoddard @tkellen any assistance diagnosing what I'm doing wrong would be appreciated!

(if you run npm run docs-dev, it should start grunt docs-examples-dev and the Jekyll server simultaneously)

[tkellen]

I would love to help but my webpack skills are quite lacking these days!

[kadamwhite]

@mzgoddard helped me sort it out; the issue was my misinterpretation of where the hmre exclusion was occurring, which lead to removal of the (necessary) build-env grunt task. This is ready for review now.

Open Q: should we commit the build examples into the repo, or should we include grunt build-examples as a post-install step, if people want to run the docs locally? I can set up boxart-boiler.github.io to include them without needing them to be committed, so I'm leaning towards making it an opt-in step when you run the docs.

(the other option would be to have the docs examples built every time you run grunt docs, which would be a lot less mental overhead, but does make the docs generation task slower...)

Although, now that I think of it, I believe my vote is to make grunt docs build the examples and then run the jekyll watch, and grunt jekyll can be used to do just the latter. Fewer tasks > More Tasks.