Add Python client docs (#1519)

Author: deliahu

Makefile

@@ -147,7 +147,7 @@ aws-clear-bucket:
 tools:
 	@go get -u -v golang.org/x/lint/golint
 	@go get -u -v github.com/VojtechVitek/rerun/cmd/rerun
-	@python3 -m pip install black
+	@python3 -m pip install black 'pydoc-markdown>=3.0.0,<4.0.0'
 	@if [[ "$$OSTYPE" == "darwin"* ]]; then brew install parallel; elif [[ "$$OSTYPE" == "linux"* ]]; then sudo apt-get install -y parallel; else echo "your operating system is not supported"; fi
 
 format:

dev/generate_python_client_md.sh

@@ -0,0 +1,74 @@
+#!/bin/bash
+
+# Copyright 2020 Cortex Labs, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+set -euo pipefail
+
+if [[ "$OSTYPE" != "linux"* ]]; then
+  echo "error: this script is only designed to run on linux"
+  exit 1
+fi
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")"/.. >/dev/null && pwd)"
+
+pip3 uninstall -y cortex
+
+cd $ROOT/pkg/workloads/cortex/client
+
+pip3 install -e .
+
+pydoc-markdown -m cortex -m cortex.client --render-toc > $ROOT/docs/miscellaneous/python_client.md
+
+# title
+sed -i "s/# Table of Contents/# Python client\n\n_WARNING: you are on the master branch, please refer to the docs on the branch that matches your \`cortex version\`_/g" $ROOT/docs/miscellaneous/python_client.md
+
+# delete links
+sed -i "/<a name=/d" $ROOT/docs/miscellaneous/python_client.md
+
+# delete unnecessary section headers
+sed -i "/_](#cortex\.client\.Client\.__init__)/d" $ROOT/docs/miscellaneous/python_client.md
+sed -i "/\* \[Client](#cortex\.client\.Client)/d" $ROOT/docs/miscellaneous/python_client.md
+# fix section link/header
+sed -i "s/\* \[cortex\.client](#cortex\.client)/\* [cortex\.client\.Client](#cortex-client-client)/g" $ROOT/docs/miscellaneous/python_client.md
+sed -i "s/# cortex\.client/# cortex\.client\.Client/g" $ROOT/docs/miscellaneous/python_client.md
+# delete unnecessary section body
+sed -i "/# cortex.client.Client/,/## deploy/{//!d}" $ROOT/docs/miscellaneous/python_client.md
+sed -i "s/# cortex.client.Client/# cortex.client.Client\n/g" $ROOT/docs/miscellaneous/python_client.md
+
+# fix table of contents links
+sed -i "s/](#cortex\./](#/g" $ROOT/docs/miscellaneous/python_client.md
+sed -i "s/](#client\.Client\./](#/g" $ROOT/docs/miscellaneous/python_client.md
+
+# indentdation
+sed -i "s/    \* /  \* /g" $ROOT/docs/miscellaneous/python_client.md
+sed -i "s/#### /## /g" $ROOT/docs/miscellaneous/python_client.md
+
+# whitespace
+sed -i 's/[[:space:]]*$//' $ROOT/docs/miscellaneous/python_client.md
+truncate -s -1 $ROOT/docs/miscellaneous/python_client.md
+
+pip3 uninstall -y cortex
+
+cat << EOF
+
+#### MANUAL EDITS REQUIRED ####
+
+- Copy the docstring for \`client(env: str)\` in pkg/workloads/cortex/client/__init__.py into the generated docs and unindent
+
+Then check the diff
+EOF
+
+# TODO automate? test on mac?

docs/miscellaneous/python_client.md

@@ -0,0 +1,264 @@
+# Python client
+
+_WARNING: you are on the master branch, please refer to the docs on the branch that matches your `cortex version`_
+
+* [cortex](#cortex)
+  * [client](#client)
+  * [local\_client](#local_client)
+  * [cluster\_client](#cluster_client)
+  * [env\_list](#env_list)
+  * [env\_delete](#env_delete)
+* [cortex.client.Client](#cortex-client-client)
+  * [deploy](#deploy)
+  * [get\_api](#get_api)
+  * [list\_apis](#list_apis)
+  * [get\_job](#get_job)
+  * [refresh](#refresh)
+  * [delete\_api](#delete_api)
+  * [stop\_job](#stop_job)
+  * [stream\_api\_logs](#stream_api_logs)
+  * [stream\_job\_logs](#stream_job_logs)
+
+# cortex
+
+## client
+
+```python
+client(env: str)
+```
+
+Initialize a client based on the specified environment.
+
+To deploy and manage APIs on a new cluster:
+
+1. Spin up a cluster using the CLI command `cortex cluster up`.
+    An environment named "aws" will be created once the cluster is ready.
+2. Initialize your client:
+
+    ```python
+    import cortex
+    c = cortex.client("aws")
+    c.deploy("./cortex.yaml")
+    ```
+
+To deploy and manage APIs on an existing cluster:
+
+1. Use the command `cortex cluster info` to get the Operator Endpoint.
+2. Configure a client to your cluster:
+
+    ```python
+    import cortex
+    c = cortex.cluster_client("aws", operator_endpoint, aws_access_key_id, aws_secret_access_key)
+    c.deploy("./cortex.yaml")
+    ```
+
+To deploy and manage APIs locally:
+
+```python
+import cortex
+c = cortex.client("local")
+c.deploy("./cortex.yaml")
+```
+
+**Arguments**:
+
+- `env` - Name of the environment to use.
+
+
+**Returns**:
+
+  Cortex client that can be used to deploy and manage APIs in the specified environment.
+
+## local\_client
+
+```python
+local_client(aws_access_key_id: str, aws_secret_access_key: str, aws_region: str) -> Client
+```
+
+Initialize a client to deploy and manage APIs locally.
+
+The specified AWS credentials will be used by the CLI to download models
+from S3 and authenticate to ECR, and will be set in your Predictor.
+
+**Arguments**:
+
+- `aws_access_key_id` - AWS access key ID.
+- `aws_secret_access_key` - AWS secret access key.
+- `aws_region` - AWS region.
+
+
+**Returns**:
+
+  Cortex client that can be used to deploy and manage APIs locally.
+
+## cluster\_client
+
+```python
+cluster_client(name: str, operator_endpoint: str, aws_access_key_id: str, aws_secret_access_key: str) -> Client
+```
+
+Create a new environment to connect to an existing Cortex Cluster, and initialize a client to deploy and manage APIs on that cluster.
+
+**Arguments**:
+
+- `name` - Name of the environment to create.
+- `operator_endpoint` - The endpoint for the operator of your Cortex Cluster. You can get this endpoint by running the CLI command `cortex cluster info`.
+- `aws_access_key_id` - AWS access key ID.
+- `aws_secret_access_key` - AWS secret access key.
+
+
+**Returns**:
+
+  Cortex client that can be used to deploy and manage APIs on a Cortex Cluster.
+
+## env\_list
+
+```python
+env_list() -> list
+```
+
+List all environments configured on this machine.
+
+## env\_delete
+
+```python
+env_delete(name: str)
+```
+
+Delete an environment configured on this machine.
+
+**Arguments**:
+
+- `name` - Name of the environment to delete.
+
+# cortex.client.Client
+
+## deploy
+
+```python
+ | deploy(config_file: str, force: bool = False, wait: bool = False) -> list
+```
+
+Deploy or update APIs specified in the config_file.
+
+**Arguments**:
+
+- `config_file` - Local path to a yaml file defining Cortex APIs.
+- `force` - Override any in-progress api updates.
+- `wait` - Streams logs until the APIs are ready.
+
+
+**Returns**:
+
+  Deployment status, API specification, and endpoint for each API.
+
+## get\_api
+
+```python
+ | get_api(api_name: str) -> dict
+```
+
+Get information about an API.
+
+**Arguments**:
+
+- `api_name` - Name of the API.
+
+
+**Returns**:
+
+  Information about the API, including the API specification, endpoint, status, and metrics (if applicable).
+
+## list\_apis
+
+```python
+ | list_apis() -> list
+```
+
+List all APIs in the environment.
+
+**Returns**:
+
+  List of APIs, including information such as the API specification, endpoint, status, and metrics (if applicable).
+
+## get\_job
+
+```python
+ | get_job(api_name: str, job_id: str) -> dict
+```
+
+Get information about a submitted job.
+
+**Arguments**:
+
+- `api_name` - Name of the Batch API.
+- `job_id` - Job ID.
+
+
+**Returns**:
+
+  Information about the job, including the job status, worker status, and job progress.
+
+## refresh
+
+```python
+ | refresh(api_name: str, force: bool = False)
+```
+
+Restart all of the replicas for a Realtime API without downtime.
+
+**Arguments**:
+
+- `api_name` - Name of the API to refresh.
+- `force` - Override an already in-progress API update.
+
+## delete\_api
+
+```python
+ | delete_api(api_name: str, keep_cache: bool = False)
+```
+
+Delete an API.
+
+**Arguments**:
+
+- `api_name` - Name of the API to delete.
+- `keep_cache` - Whether to retain the cached data for this API.
+
+## stop\_job
+
+```python
+ | stop_job(api_name: str, job_id: str, keep_cache: bool = False)
+```
+
+Stop a running job.
+
+**Arguments**:
+
+- `api_name` - Name of the Batch API.
+- `job_id` - ID of the Job to stop.
+
+## stream\_api\_logs
+
+```python
+ | stream_api_logs(api_name: str)
+```
+
+Stream the logs of an API.
+
+**Arguments**:
+
+- `api_name` - Name of the API.
+
+## stream\_job\_logs
+
+```python
+ | stream_job_logs(api_name: str, job_id: str)
+```
+
+Stream the logs of a Job.
+
+**Arguments**:
+
+- `api_name` - Name of the Batch API.
+- `job_id` - Job ID.

docs/summary.md

@@ -48,6 +48,7 @@
 ## Miscellaneous
 
 * [CLI commands](miscellaneous/cli.md)
+* [Python client](miscellaneous/python_client.md)
 * [Environments](miscellaneous/environments.md)
 * [Architecture diagram](miscellaneous/architecture.md)
 * [Security](miscellaneous/security.md)