improve the python api docs

Author: williamstein

src/python/cocalc-api/docs/api/organizations.md

@@ -1 +1,7 @@
+Please contact support at [[email protected]](mailto:[email protected]) if you would like to manage an
+organization. Tell us what you're doing, and select an organization name, title,
+description, email address, and url. We will then create your organization and
+make your account an admin of the organization. You will then be able to create
+new users in your org and generate a temporary authentication link for any user.
+
 ::: cocalc_api.hub.Organizations

src/python/cocalc-api/docs/index.md

@@ -1,12 +1,22 @@
 # CoCalc Python API Client
 
-
-Install the Python client API `cocalc-api` that is [hosted on Pypi](
-https://pypi.org/project/cocalc-api/).
-
+Install the Python client API `cocalc-api` that is [hosted on Pypi](https://pypi.org/project/cocalc-api/).
 
 ```sh
 pip install cocalc-api
 ```
 
-Obtain a [CoCalc account API Key](https://doc.cocalc.com/apikeys.html), then start using CoCalc from your Python scripts.
+Obtain a [CoCalc account API Key](https://doc.cocalc.com/apikeys.html) by going to [your account preferences](https://cocalc.com/settings/account) and scrolling down to "Api Keys", then start using CoCalc from your Python scripts. This API is mostly for account level API keys, but it also provides some minimal support for project specific API keys.
+
+Using an account level API key, the cocalc_api Python library enabled you to do all of the following very easily from a Python script:
+
+- [search](api/system/) for other cocalc users by name or email address, and get the name associated to an account_id
+- list [your projects](api/projects), add and remove collaborators, copy files between projects and start, stop and create projects.
+- use the [Jupyter API](api/jupyter) to evaluate code using a kernel, either in an anonymous sandbox or in one of your projects.
+- read or write any data you have access to in the CoCalc [PostgreSQL database](api/database), as defined by [this schema](https://github.com/sagemathinc/cocalc/tree/master/src/packages/util/db-schema).
+- instantly send and receive [messages](api/messages) with any other cocalc users
+- create and manage users in an [organization](api/organizations), including automatically generating authentication links, so you're users do not have explicitly create a CoCalc account. You can see when they are active and send them messages.
+
+Currently a project specific API key can be used to:
+
+- Run [shell commands](api/project) and Jupyter code in a specific project.

src/python/cocalc-api/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cocalc-api"
-version = "0.3.0"
+version = "0.4.0"
 description = "Python client for the CoCalc API"
 authors = [{ name="William Stein", email="[email protected]" }]
 readme = "README.md"