Add some creation context to Client docs

[jsignell]

This came out of @martindurant's suggestion in #6804

[martindurant]

So then the API page should point here and say that it is strictly reference? Should the docstring for Client contain any of this?

[jsignell]

So then the API page should point here and say that it is strictly reference?

That would probably be the cleanest solution. The API should be just reference, and this kind of explanation and context should be in a narrative doc (like this one).

Should the docstring for Client contain any of this?

The docstring already has a version of this.

[martindurant]

The docstring already has a version of this.

Perhaps I should have said: a better version than already exists there :)

[jsignell]

The docstring already has a version of this.

Perhaps I should have said: a better version than already exists there :)

🥲 yes please feel free to update that!

[jsignell]

Ping @scharlottej13 for visibility

[martindurant]

Current docstring:

Connect to and submit computation to a Dask cluster

The Client connects users to a Dask cluster. It provides an asynchronous
user interface around functions and futures. This class resembles
executors in concurrent.futures but also allows Future objects
within submit/map calls. When a Client is instantiated it takes over
all dask.compute and dask.persist calls by default.

It is also common to create a Client without specifying the scheduler
address , like Client(). In this case the Client creates a
:class:LocalCluster in the background and connects to that. Any extra
keywords are passed from Client to LocalCluster in this case. See the
LocalCluster documentation for more information.

Parameters

address: string, or Cluster
This can be the address of a Scheduler server like a string
'127.0.0.1:8786' or a cluster object like LocalCluster()

[github-actions]

Unit Test Results

See test report for an extended history of previous test failures. This is useful for diagnosing flaky tests.

       15 files  ±0         15 suites  ±0   6h 39m 54s ⏱️ + 28m 14s
  2 977 tests ±0    2 883 ✔️  - 1       88 💤 +1  3 ❌  - 2  3 🔥 +2 
22 074 runs  +2  21 034 ✔️ ±0  1 031 💤 +2  5 ❌  - 3  4 🔥 +3 

For more details on these failures and errors, see this check.

Results for commit ee74182. ± Comparison against base commit 236945a.