Documentation generation (#10)

* Script to generate docs for local packages * Add Jekyll site * Add example jsdoc for construct * Use GFM for proper rendering * Add log for build process * Add doc footer content * Prefer lowercase title * Add website helper command * Cleanup script * Add link to earthdata-playbook * Mv earthdata-playbook link to footer, link to Github * Improve build tools * Update contribution guidelines * Small jekyll updates * Add docs on building documentation * Update README.md * Update docgen.js * Apply suggestions from code review * Update scripts/docgen.js

Author: alukach

.gitignore

@@ -1,3 +1,4 @@
 node_modules/
 npm-debug.log
 lerna-debug.log
+docs

.ruby-version

@@ -0,0 +1 @@
+2.7.2

CONTRIBUTING.md

@@ -3,6 +3,56 @@
 1. Create empty package: `npx lerna create @cdk-seed/<package-name>`
 1. Prepare package: `npx jsii-config-p ./packages/<package-name>/package.json`
 
+All TypeScript tooling is managed by [`jsii`](https://github.com/aws/jsii) and generated by running `npm build`. There is no need to add or modify TypeScript build configuration (e.g. `tsconfig.json`).
+
+## Documentation
+
+To support others who want to use our distributed constructs, we want to ensure that each package distributed by CDK Seed is well documented.
+
+### README
+
+Each package should contain a `README.md` at its root. We use [Github Flavored Markdown](https://guides.github.com/features/mastering-markdown/#GitHub-flavored-markdown) to render the content into HTML. The README should be formatted as follows:
+
+```markdown
+# <!--Construct Name -->
+
+<!-- A brief description of what the construct's purpose -->
+
+## Use Cases
+
+<!-- Some examples of when a user may want to utilize this construct -->
+
+## Examples
+
+<!-- Examples of how to use the construct -->
+
+## Requirements
+
+<!-- Expectations of user's VPC configuration, etc -->
+```
+
+Code samples can be included alongside text within in markdown files as such:
+
+ <div class="code-example">
+
+ Below is an example of doing something with code!
+
+ </div>
+
+ ```ts
+ console.log("Look, I'm doing something!")
+ ```
+
+For more UI components, see the [Just the Docs](https://pmarsceill.github.io/just-the-docs/docs/ui-components) documentation.
+
+_NOTE: Just the Docs' examples utilize Kramdown to render its markdown, not Github Flavored Markdown. Being that we use Github Flavored Markdown, shorthand such as `{: .btn }` is not available. Any non-standard markdown should be written as HTML._
+
+### JSDocs
+
+Code documentation is generated automatically from the [JSDoc](https://jsdoc.app/) comment blocks provided within the TypeScript source code. At a minimum, every member of the `props` interface and the exported `Construct` should be annotated with JSDoc information. 
+
+ _NOTE: At time of writing, it appears that only the `@deprecated` tag makes its way from the JSDoc annotations to the rendered markdown. As such, content from other tags (e.g. `@default`) should be duplicated within the textual messaging of the JSDoc description._
+
 ## Additional Resources
 
 - [jsii - Getting Started](https://github.com/aws/jsii#getting-started)

README.md

@@ -18,6 +18,10 @@ If you get an error that the version of node is not installed, run:
 
 ### Commands
 
+#### `npm start`
+
+Watch packages for updates to code and documentation, triggering builds of both on change.
+
 #### `npm run bootstrap`
 
 Install dependencies for each package.
@@ -41,3 +45,18 @@ Run tests for all packages.
 ## Adding packages
 
 See [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+## Generating documentation
+
+The generation of our documentation website is a three part process:
+
+1. `jsii` must be run within each package (this is done by running `npm run build` from the project base dir). This produces a `.jsii` in the root of each package.
+2. `scripts/docgen.js` should be run to gather each package's `.jsii` file and to export markdown documentation for each package into the `site/docs` directory.
+3. [Jekyll](https://jekyllrb.com/) should be run to generate HTML from the markdown documentation.
+
+This process can be made easier by running two processes in separate terminals:
+
+1. `npm start` which concurrently runs two operations:
+ * trigger `jsii` builds on changes to packages' `README.md` or `lib/*.ts` files.
+ * trigger `scripts/docgen.js` to run on changes to packages' `.jsii` files.
+2. `npm run website` which starts the Jekyll server. It is assumed that Jekyll has been previously installed on the system. See [Jekyll's documentation](https://jekyllrb.com/docs/installation/) for more information.