Update secret documentation as well

docs/cloud/cloud_concepts/secrets.md

@@ -29,7 +29,7 @@ KEY = VALUE
 with however many key / value pairs you'd like.
 
 ::: tip You don't have to store raw values in your config
-Prefect will interpolate certain values from your OS environment, so you can specify values from environment variables via `"$ENV_VAR"`.
+Prefect will interpolate certain values from your OS environment, so you can specify values from environment variables via `"$ENV_VAR"`.  Note that secrets set this way will always result in lowercase names.
 :::
 
 ### Cloud Execution

docs/outline.toml

@@ -24,7 +24,7 @@ classes = ["Client"]
 
 [pages.client.secrets]
 title = "Secrets"
-module = "prefect.client"
+module = "prefect.client.secrets"
 classes = ["Secret"]
 
 [pages.schedules.schedules]

src/prefect/client/secrets.py

@@ -1,3 +1,36 @@
+"""
+A Secret is a serializable object used to represent a secret key & value.
+
+The value of the `Secret` is not set upon initialization and instead is set
+either in `prefect.context` or on the server, with behavior dependent on the value
+of the `use_local_secrets` flag in your Prefect configuration file.
+
+To set a Secret in Prefect Cloud, you can use `prefect.Client.set_secret`, or set it directly via GraphQL:
+
+```graphql
+mutation {
+  setSecret(input: { name: "KEY", value: "VALUE" }) {
+    success
+  }
+}
+```
+
+To set a _local_ Secret, either place the value in your user configuration file (located at `~/.prefect/config.toml`):
+
+```
+[context.secrets]
+MY_KEY = "MY_VALUE"
+```
+
+or directly in context:
+
+```python
+import prefect
+
+prefect.context.secrets["MY_KEY"] = "MY_VALUE"
+```
+"""
+
 import json
 import os
 from typing import Any, Optional