Expand docs around the deprecation of former secret syntax (#4561)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Thomas Anderson <127358482+zc-devs@users.noreply.github.com>
Co-authored-by: qwerty287 <80460567+qwerty287@users.noreply.github.com>

docs/docs/20-usage/40-secrets.md

@@ -11,17 +11,27 @@ Woodpecker provides three different levels to add secrets to your pipeline. The
 
 ## Usage
 
-You can set a setting or an environment value from secrets using the `from_secret` syntax.
+You can set a setting or environment value from secrets using the `from_secret` syntax.
 
-In this example, the secret named `secret_token` would be passed to the setting named `token`,which will be available in the plugin as environment variable named `PLUGIN_TOKEN` (See [plugins](./51-plugins/20-creating-plugins.md#settings) for details), and to the environment variable `TOKEN_ENV`.
+The example below passes a secret called `secret_token` as an environment variable that will be called `TOKEN_ENV`:
 
 ```diff
  steps:
-   - name: docker
+   env-secret-example:
-     image: my-plugin
+     image: alpine
+     commands:
++      - echo "The secret is $TOKEN_ENV"
 +    environment:
 +      TOKEN_ENV:
 +        from_secret: secret_token
+```
+
+You can use the same syntax to pass secrets to settings. For example, you can pass a secret named `secret_token` to the settings called `token`, which will then be available in the plugin as environment variable named `PLUGIN_TOKEN` (See [plugins](./51-plugins/20-creating-plugins.md#settings) for details).
+
+```diff
+ steps:
+   - name: settings-secret-example
+     image: my-plugin
 +    settings:
 +      token:
 +        from_secret: secret_token

docs/versioned_docs/version-2.8/20-usage/40-secrets.md

@@ -13,6 +13,12 @@ Woodpecker provides three different levels to add secrets to your pipeline. The
 
 ### Use secrets in commands
 
+:::warning
+The use of secrets is deprecated as of version 2.8 and planned to be removed with version 3.
+Instead, you can use the *secrets in settings and environment* approach outlined below.
+You can already migrate to this strategy with version 2.8.
+:::
+
 Secrets are exposed to your pipeline steps and plugins as uppercase environment variables and can therefore be referenced in the commands section of your pipeline,
 once their usage is declared in the `secrets` section:
 
@@ -30,17 +36,27 @@ The case of the environment variables is not changed, but secret matching is don
 
 ### Use secrets in settings and environment
 
-You can set an setting or environment value from secrets using the `from_secret` syntax.
+You can set a setting or environment value from secrets using the `from_secret` syntax.
 
-In this example, the secret named `secret_token` would be passed to the setting named `token`,which will be available in the plugin as environment variable named `PLUGIN_TOKEN` (See [plugins](./51-plugins/20-creating-plugins.md#settings) for details), and to the environment variable `TOKEN_ENV`.
+The example below passes a secret called `secret_token` as an environment variable that will be called `TOKEN_ENV`:
 
 ```diff
  steps:
-   - name: docker
+   env-secret-example:
-     image: my-plugin
+     image: alpine
+     commands:
++      - echo "The secret is $TOKEN_ENV"
 +    environment:
 +      TOKEN_ENV:
 +        from_secret: secret_token
+```
+
+You can use the same syntax to pass secrets to settings. For example, you can pass a secret named `secret_token` to the settings called `token`, which will then be available in the plugin as environment variable named `PLUGIN_TOKEN` (See [plugins](./51-plugins/20-creating-plugins.md#settings) for details).
+
+```diff
+ steps:
+   - name: settings-secret-example
+     image: my-plugin
 +    settings:
 +      token:
 +        from_secret: secret_token