feat: improve documentation (#90) (#4)

Co-authored-by: db <[email protected]>

README.md

@@ -4,52 +4,7 @@
 
 To get started with the IoT Application Kit and the AWS IoT SiteWise source, see [Getting Started](https://github.com/awslabs/iot-app-kit/tree/main/docs/Core.md).
 
-To learn more about IoT Application Kit components, sources, and the core API see [docs](https://github.com/awslabs/iot-app-kit/tree/main/docs/).
-
-## Quick start for development
-
-1. Environment setup
-
-Ensure you have node version 16 and the latest version of yarn installed.
-
-
-To do this, execute the following commands:
-```
-# Install `n`, a node package manager, globally to help switch between node versions.
-npm i n -g
-
-# Update to node version 16
-sudo n 16
-
-# Install the latest version of yarn
-npm i yarn@latest -g
-
-# Optionally, install lerna
-npm i lerna -g
-```
-
-2. Build project
-
-```
-# Without installing lerna locally...
-npx lerna bootstrap
-
-# With lerna installed locally
-lerna bootstrap
-```
-
-4. Provide credentials
-Copy a set of AWS JSON formatted credentials to the account with the access to the SiteWise resources you are requesting, at `<rootDir>/packages/components/creds.json`.
-
-These credentials should not be uploaded to the repository.
-
-5. Point to valid SiteWise resources
-
-Alter the file `siteWiseQueries` within `@iot-app-kit/components` to point to valid SiteWise asset properties for the accounts credentials from the prior step.
-
-3. Test locally
-run `yarn run start` at the project root, and then view `localhost:3333`. Here you should see example IoT App Kit components requesting data from SiteWise.
-
+To learn more about IoT Application Kit components, sources, and the core API see [docs](https://github.com/awslabs/iot-app-kit/tree/main/docs/TOC.md).
 
 ## Packages
 
@@ -83,6 +38,9 @@ The IoT Application Kit mono-repo containing the following packages:
 ## Security
 See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
 
+## Developing iot-app-kit
+Working on building or contributing to iot-app-kit itself? see [the development guide](https://github.com/awslabs/iot-app-kit/tree/main/docs/development.md).
+
 ## License
 This project is licensed under the Apache-2.0 License.
 

docs/GettingStarted.md

@@ -2,11 +2,15 @@
 
 Use the step-by-step tutorial in this section to learn how to set up IoT Application Kit. 
 
-1. To install the `@iot-app-kit/source-iotsitewise` module, choose one of the following.
+1. Install the required dependencies
     1.  To install by using npm, run the following command.
         1. `npm install --save @iot-app-kit/source-iotsitewise`
+        1. `npm install --save @iot-app-kit/components`
+        1.  If you want to use React: `npm install --save @iot-app-kit/react-components`
     2. To install by using Yarn, run the following command.
         1. `yarn add @iot-app-kit/source-iotsitewise`
+        1. `yarn add @iot-app-kit/components`
+        1. `yarn add @iot-app-kit/react-components`
 2. To initialize the AWS IoT SiteWise source, choose one of the following. 
     1. To initialize an instance of [@aws-sdk/client-iotsitewise](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-iotsitewise/index.html), use the following sample code.
 
@@ -32,15 +36,18 @@ Use the step-by-step tutorial in this section to learn how to set up IoT Applica
 
             const { query } = initialize({ awsCredentials: fromEnv() });
 
-3. To mount the component, use the following sample code. 
+3. Include the style sheets somewhere in your application
+
+```
+import "@iot-app-kit/components/styles.css";
+```
+
+4. To mount the component, use the following sample code. 
 
         import { initialize } from '@iot-app-kit/source-iotsitewise';
         import { LineChart, WebGLContext } from '@iot-app-kit/react-components';
         import { fromEnv } from "@aws-sdk/credential-providers";
 
-        // import component stylesheet
-        import "@iot-app-kit/components/dist/iot-app-kit-components/iot-app-kit-components.css";
-
         // initialize source-iotsitewise
         const { query } = initialize({
           awsCredentials: fromEnv()

docs/ResourceExplorer.md

@@ -12,21 +12,6 @@ Query Type: `TreeQuery<SiteWiseAssetTreeNode[], BranchReference>`
 
 **Required: Yes**
 
-```
-export interface Query<Result, Params = void> {
-  build(sessionId: string, params?: Params): Provider<Result>;
-}
-
-export interface TreeProvider<Result, Branch> extends Provider<Result> {
-  expand(branch: Branch): void;
-  collapse(branch: Branch): void;
-}
-
-export interface TreeQuery<Result, Branch, Params = void> extends Query<Result, Params> {
-  build(sessionId: string, params?: Params): TreeProvider<Result, Branch>;
-}
-```
-
 ### columnDefinitions
 
 The columns defined in the table. By default, the resource explorer table contains the following column names: `Name`, `Status`, `Creation Date`, and `Last Update Date`.
@@ -40,57 +25,39 @@ The columns defined in the table. By default, the resource explorer table contai
 * `ariaLabel` (LabelData => string) - You can optionally specify an `aria-label` for the cell header. It receives the current sorting state of this column, the direction it's sorted in, and an indication of whether the sorting is disabled, as three Boolean values: `sorted`, `descending` and `disabled`. We recommend that you use this for sortable columns to provide more meaningful labels based on the current sorting direction.
 
 Type: ReadonlyArray<ColumnDefinition>
-Required: No
-
-```
-`ColumnDefinition<T> ``{`
-`  id``?:`` ``string``;`
-`  header``:`` ``string``;`
-`  cell``:`` ``(``item``:`` T``)`` ``=>`` ``string`` ``|`` ``undefined``;`
-`  ariaLabel``?(``data``:`` ``LabelData``):`` ``string``;`
-`  width``?:`` number ``|`` ``string``;`
-`  minWidth``?:`` number ``|`` ``string``;`
-`  maxWidth``?:`` number ``|`` ``string``;`
-`}`
-```
 
 ### selectionType
 
 The selection type.
 Type: Enum string
 Valid values:  `single | multi`
 Default: `single`
-Required: No
 
 ### loadingText
 
 The loading message appears when the table enters the loading state.
 Type: String
-Required: No
 
 ### filterEnabled
 
 Whether or not to enable the filter. If `false`, the filter box won’t appear.
 Type: Boolean
 Default: `true`
 Valid values: `true | false`
-Required: No
 
 ### sortingEnabled
 
 Whether or not to enable the sorting. If `false`, the sorting buttons won’t appear.
 Type: Boolean
 Default: `true`
 Valid values: `true | false`
-Required: No
 
 ### paginationEnabled
 
 Whether or not to enable the pagination. If `false`, the table displays all rows on a single page at once. If `true`, the table displays 20 rows for each page.
 Type: Boolean
 Default: `true`
 Valid values: `true | false`
-Required: No
 
 ### filterTexts
 

docs/development.md

@@ -0,0 +1,45 @@
+## Quick start for development
+
+1. Environment setup
+
+Ensure you have node version 16 and the latest version of yarn installed.
+
+
+To do this, execute the following commands:
+```
+# Install `n`, a node package manager, globally to help switch between node versions.
+npm i n -g
+
+# Update to node version 16
+sudo n 16
+
+# Install the latest version of yarn
+npm i yarn@latest -g
+
+# Optionally, install lerna
+npm i lerna -g
+```
+
+2. Build project
+
+```
+# Without installing lerna locally...
+npx lerna bootstrap
+
+# With lerna installed locally
+lerna bootstrap
+```
+
+4. Provide credentials
+   Copy a set of AWS JSON formatted credentials to the account with the access to the SiteWise resources you are requesting, at `<rootDir>/packages/components/creds.json`.
+
+These credentials should not be uploaded to the repository.
+
+5. Point to valid SiteWise resources
+
+Alter the file `siteWiseQueries` within `@iot-app-kit/components` to point to valid SiteWise asset properties for the accounts credentials from the prior step.
+
+6. Test locally
+   run `yarn run start` at the project root, and then view `localhost:3333`. Here you should see example IoT App Kit components requesting data from SiteWise.
+
+