Documentation generation

[alukach]

This PR does two things:

1. Adds a script for documentation generation.
2. Sets up a Jekyll site to host the documentation.

Script for Documentation Generation

Moves documentation generation from a lerna command that generates document on each package to a single script (scripts/docgen.js) that generates documentation for each package. This script works much like the jsii-docgen, but with a few exceptions:

1. Any module not prefaced with @cdk-seed is ignored
2. documentation is prepended with Jekyll Front Matter content
3. links to AWS constructs are directed to the official AWS CDK documentation.

https://github.com/developmentseed/cdk-seed/blob/0d9927a09b42418123567c38973de44b811bb083/scripts/docgen.js#L1-L9

Jekyll Site

A Jekyll site has been added in the site directory. This runs the Just The Docs theme which provides search out of the box. We utilize the front matter generated when we create our documentation markdown to create a sense of hierarchy to the modules (i.e. the README.md of each package renders as a link in the side-navbar, the classes and props of each package render as links under that README.md's documentation).

The process to generate documentation is a bit intricate, I attempted to capture the steps here:

https://github.com/developmentseed/cdk-seed/blob/b887955cea8b52f9b1fa8360bb27f760c6972f41/README.md#L49-L62

The act of creating helper commands to watch for new builds and new documentation was a bit wild for the following reasons:

1. jsii supports a -w flag for running in watch mode to generate .jsii files on changes to the *.ts files, however it does not trigger rebuilds on changes to README.md files (however, those README.md files are used to generate .jsii files). For this reason, I had to wrap the command in another watch command with nodemon.
2. nodemon does not do well watching files without filenames (i.e. files that are only extensions, such as .env or .jsii). For this reason, we need to manually discover and add each .jsii filepath as a -w command to nodemon ($(for f in packages/*/.jsii; do echo \"-w $f\"; done)). Related issue.

https://github.com/developmentseed/cdk-seed/blob/b887955cea8b52f9b1fa8360bb27f760c6972f41/package.json#L16-L22

---

Ultimately, I don't believe that jsii-docgen is the best tool for documentation generation. It gets us a lot for not much effort (docgen from both code and README.md), but it doesn't seem to display any JSDoc blocktags aside from @deprecated (which only renders with a warning triangle, but no message, issue). After doing some research, I think something like using TypeDoc to generate JSON which is then parsed and rendered by Jekyll would give much greater control about the UI elements but would require much more work (blogpost on topic).

https://github.com/developmentseed/cdk-seed/blob/b887955cea8b52f9b1fa8360bb27f760c6972f41/CONTRIBUTING.md#L50

[alukach]

Resolves #4, however it does not autodeploy to Github Pages (that should be covered in #3)

[alukach]

Thanks for the review @botanical, I'm in agreement on all suggestions and have made changes in a01501c.

[alukach]

@botanical Thanks Jennifer. Were you able to build the documentation locally?

[botanical]

@botanical Thanks Jennifer. Were you able to build the documentation locally?

Yes 🎉

It makes me think of one thing - maybe in another PR we can add a troubleshooting page for things like if a user runs into:

[1] > root@ docgen /Users/jennifertran/Code/ds/cdk-seed
[1] > node ./scripts/docgen.js --output site/docs 'packages/**/.jsii'
[1]
[1] (node:80263) ExperimentalWarning: The ESM module loader is experimental.
[1] file:///Users/jennifertran/Code/ds/cdk-seed/scripts/docgen.js:65
[1]   const output = args.output ?? "dist";
[1]                               ^
[1]
[1] SyntaxError: Unexpected token '?'
[1]     at Loader.moduleStrategy (internal/modules/esm/translators.js:122:18)
[1]     at async link (internal/modules/esm/module_job.js:42:21)
[1] npm ERR! code ELIFECYCLE
[1] npm ERR! errno 1
[1] npm ERR! root@ docgen: `node ./scripts/docgen.js --output site/docs 'packages/**/.jsii'`
[1] npm ERR! Exit status 1
[1] npm ERR!
[1] npm ERR! Failed at the root@ docgen script.
[1] npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

then we can suggest they remember to run nvm use.

That's the only gotcha I ran into because I am using different node versions for different projects. Just a thought 😄