Add typedoc and inline documentation (#71)

## Problem

We need a way to create inline documentation in our source code.

## Solution

- Use [typedoc](https://typedoc.org/guides/overview/) as a
devDependency. This project takes heavy inspiration from the much older
jsdoc project but is compatible with typescript.
- Add initial docs about client methods landed to master
- Add `@deprecated` attribute to old client.

## Type of Change

- [x] Docs

## Test Plan

Describe specific steps for validating this change.

.gitignore

@@ -6,3 +6,4 @@ src/run.ts
 .vscode
 .DS_Store
 scratch
+docs/

README.future.md

@@ -18,16 +18,83 @@ const client = await Pinecone.createClient({
 
 It also can find information specified in the environment variables `PINECONE_API_KEY` and `PINECONE_ENVIRONMENT`.
 
-## Data Plane
+## Control Plane
+
+### Create an index
+
+The minimum required configuration to create an index is the index name and dimension. The dimension you choose should match the output of the model used to produce your embeddings.
+
+```
+await client.createIndex({ name: 'my-index', dimension: 128 })
+```
+
+In a more expansive example, you can specify the metric, number of pods, number of replicas, and pod type.
+
+```
+await client.createIndex({
+ name: 'my-index',
+ dimension: 128,
+ metric: 'cosine',
+ pods: 1,
+ replicas: 2,
+ podType: 'p1.x1'
+})
+```
+
+By default all metadata fields are indexed when vectors are upserted with metadata, but if you want to improve performance you can specify the specific fields you want to index. This example is showing a few hypothetical metadata fields, but the values you'd use depend on what metadata you plan to store in Pinecone alongside your vectors.
+
+```
+await client.createIndex({ name: 'my-index', dimension: 128, metadataConfig: { 'indexed' : ['productName', 'productDescription'] }})
+```
+
+### Describe an index
+
+After you've created an index, you can view its configuration.
+
+```
+const config = await client.describeIndex('my-index')
+// {
+//   database: {
+//     name: 'my-index',
+//     metric: 'cosine',
+//     pods: 1,
+//     replicas: 1,
+//     shards: 1,
+//     podType: 'p1.x1'
+//   },
+//   status: { ready: false, state: 'Ready' }
+// }
+```
 
 ### List indexes
 
 ```
-client.listIndexes()
+const indexList = await client.listIndexes()
+// ['my-index']
+```
+
+### Delete an index
+
+```
+await client.deleteIndex('my-index')
 ```
 
-### Describe index
+### Configure an index
+
+You can adjust the number of replicas or scale to a larger pod size (specified with `podType`). See [Pod types and sizes](https://docs.pinecone.io/docs/indexes#pods-pod-types-and-pod-sizes). You cannot downgrade pod size or change the base pod type.
 
 ```
-client.describeIndex('my-index-name')
+await client.configureIndex('my-index', { replicas: 3, podType: 'p1.x2' })
+const config = await client.describeIndex('my-index')
+// {
+//   database: {
+//     name: 'my-index',
+//     metric: 'cosine',
+//     pods: 3,
+//     replicas: 3,
+//     shards: 1,
+//     podType: 'p1.x2'
+//   },
+//   status: { ready: false, state: 'ScalingUpPodType' }
+// }
 ```

package.json

@@ -13,6 +13,7 @@
   "license": "MIT",
   "scripts": {
     "build": "rm -rf dist/ && tsc",
+    "docs:build": "typedoc",
     "format": "prettier --write .",
     "lint": "eslint src/ --ext .ts",
     "repl": "npm run build && node utils/replInit.ts",
@@ -36,6 +37,7 @@
     "prettier": "^2.8.8",
     "ts-jest": "^29.0.5",
     "ts-node": "^10.9.1",
+    "typedoc": "^0.24.8",
     "typescript": "^4.9.4",
     "unique-names-generator": "^4.7.1"
   },