Doc and dist builds

[TrevorFSmith]

Here's an initial high-level description of a build system for discussion.

I'm using {project-name} until we decide on a name in the naming issue.

Tactics:

Write ES'15 syntax code into JS module files (one per class) and then build them into JS files for distribution.

Build using npm but do not require that projects using these libraries also use npm.

Use straight npm to call out to specific tools like webpack and docusaurus. So, no grunt or gulp.

Use webpack to generate JS files for each major library, as described in the README:

• {project name}-action.js
• {project name}-input.js
• {project name}-hardware.js
• {project-name}-config-ui.js

Also generate a single file for easy onboarding and for projects that need every library:

• {project name}-everything.js (a single file for single-inclusion quickstarts)

Also generate a minimized version of each file listed above.

Create build dirs for each library (action, input, hardware, config) that contain the JS and all library-specific data like JSON for the action maps, CSS for the config UI, and glTF for the controller models.

Create an 'everything' build dir with the {project-name}-everything.js and all of the library data mentioned above.

Documentation

Use docusaurus to generate JS API reference documents and an examples page.

Publish docs to this repo's GitHub Pages.

Not in this repo

• Large sample applications using these libraries (publish in separate repos for each Glitch publishing)

[TrevorFSmith]

@cvan Recommended that we consider Microbundle, which is a wrapper around Rollup.

[TrevorFSmith]

It looks like JSDoc3 is one of the more popular JS API reference generators. The source and installation instructions are here

[TrevorFSmith]

@joshmarinacci suggested that we also consider ESDoc.

[TrevorFSmith]

On further thought and conversation with @cvan, in order to make versioning and publishing easier, perhaps we should create a single repo and library for what was the separate action, input, and hardware libraries.

We'd create a separate repo for the config UI, since it's a UI element instead of a middle tier library and lots of projects will either not enable config UI or will provide their own.

[cvan]

Has it been considered to make a monorepo? Maintaining projects across repos is a paaaaain. Can still publish multiple npm projects from a single repo. Lots of success stories I’ve seen lately.

[TrevorFSmith]

Yeah, I'm leaning toward everything being in one repo except the config UI because it seemed so different than the other stuff.

[TrevorFSmith]

I'm open to having the UI in the same repo if we nicely partition it off in the build and publishing configs.

[netpro2k]

No strong preferences here. Has anyone had any luck with https://parceljs.org/? I have been meaning to check it out and was planning on using it for my next project.