docs: refactor config and output

.lycheeignore

@@ -8,6 +8,7 @@ https://fonts.gstatic.com/
 .*xxx.*
 .*changeme.*
 .*example.*
+.*test.*
 .*YOUR_.*
 https://id.atlassian.net
 https://JIRA_ID.atlassian.net

docs/best-practices/gitops.zh.md

@@ -1,6 +1,5 @@
 # GitOps
 
-<span id="0-目标"></span>
 ## 0 目标
 在本教程中，我们将尝试通过 DevStream 来实现以下目标：
 
@@ -38,7 +37,7 @@
 
 ## 2 概览
 
-DevStream 将使用下面的插件来实现[第 0 节](#0-目标)中描述的目标：
+DevStream 将使用下面的插件来实现[第 0 节](#)中描述的目标：
 
 1. [repo-scaffolding](../plugins/repo-scaffolding.md)
 2. [github-actions](../plugins/github-actions.md)

docs/core-concepts/config.md

@@ -2,19 +2,19 @@
 
 DevStream uses YAML files to define your DevOps platform.
 
-## Sections
+## 1 Sections Overview
 
 As aforementioned in the overview, there are several sections in the config:
 
 - `config`
-- `vars`
 - `tools`
 - `apps`
 - `pipelineTemplates`
+- `vars`
 
 Among which, `config` is mandatory, and you should have at least either `tools` or `apps`. Others are optional.
 
-## Config File V.S. Config Folder
+## 2 Config File V.S. Config Folder
 
 DevStream supports both:
 
@@ -28,11 +28,22 @@ Examples:
 - single file: `dtm init -f config.yaml`
 - directory: `dtm init -f dirname`
 
-## The Main Config
+## 3 Sections Detail
+
+### 3.1 The Main Config
 
 DevStream's own config, the `config` section, contains where to store the state. See [here](./state.md) for more details.
 
-## Variables
+
+### 3.2 Tools Config
+
+The `tools` section defines DevOps tools. Read [this](./tools.md) for all the detail.
+
+### 3.3 Apps/pipelineTemplates Config
+
+The `apps` section defines Apps and the `pipelineTemplates` defines templates for pipelines. See [here](./apps.md) for more detail.
+
+### 3.4 Variables
 
 DevStream supports variables. Define key/values in the `vars` section and refer to it in the `tools`, `apps` and `pipelineTemplates` sections.
 
@@ -58,10 +69,94 @@ tools:
     # ...
 ```
 
-## Tools Config
+## 4 Expanded Features
 
-The `tools` section defines DevOps tools. Read [this](./tools.md) for all the detail.
+### 4.1 Environment Variables
 
-## Apps/pipelineTemplates Config
+Similar to "variables", you can use `[[env "env_key"]]` to refer to environment variables.
+
+### 4.2 Output
+
+#### Introduction
+
+In DevStream's configuration file, we can use Output from one Tool as the options values for another Tool.
+
+For example, if Tool A has an output, we can use its value as Tool B's options.
+
+Notes:
+
+- At the moment, B using A's output doesn't mean B "depends on" A.
+- If B needs to "depend on" A, i.e., we want to make sure A runs first before B runs, we still need to use the `dependsOn` keyword (see the previous section "[Core Concepts](overview.md)" for more details.)
+
+#### Syntax
+
+To use the output, follow this format:
+
+```
+${{ TOOL_NAME.TOOL_INSTANCE_ID.outputs.OUTPUT_KEY }}
+```
+
+For example, given config:
+
+```yaml
+tools:
+- name: trello
+  instanceID: default
+  options:
+    owner: IronCore864
+    repo: golang-demo
+    kanbanBoardName: golang-demo-board
+```
+
+- `TOOL_NAME` is "trello"
+- `TOOL_INSTANCE_ID` is "default"
+
+If the "trello" tool/plugin has an output key name "boardId", then we can use its value by the following syntax:
+
+```
+${{ trello.default.outputs.boardId }}
+```
+
+#### Real-World Usage Example
+
+Config:
+
+```yaml hl_lines="2 3 20 31"
+tools:
+- name: repo-scaffolding
+  instanceID: golang-github
+  options:
+    destinationRepo:
+      owner: IronCore864
+      name: golang-demo
+      branch: main
+      scmType: github
+    vars:
+      imageRepo: "ironcore864/golang-demo"
+    sourceRepo:
+      org: devstream-io
+      name: dtm-scaffolding-golang
+      scmType: github
+- name: helm-installer
+  instanceID: argocd
+- name: argocdapp
+  instanceID: default
+  dependsOn: [ "helm-installer.argocd", "repo-scaffolding.golang-github" ]
+  options:
+    app:
+      name: golang-demo
+      namespace: argocd
+    destination:
+      server: https://kubernetes.default.svc
+      namespace: default
+    source:
+      valuefile: values.yaml
+      path: helm/golang-demo
+      repoURL: ${{ repo-scaffolding.golang-github.outputs.repoURL }} # pay attention here
+```
+
+In this example:
+
+- The "default" instance of tool `argocdapp` depends on the "golang-github" instance of tool `repo-scaffolding`
+- The "default" instance of tool `argocdapp` has a user option "options.source.repoURL", which uses the "golang-github" instance of tool `repo-scaffolding`'s output "repoURL" (`${{ repo-scaffolding.golang-github.outputs.repoURL }}`)
 
-The `apps` section defines Apps and the `pipelineTemplates` defines templates for pipelines. See [here](./apps.md) for more detail.

docs/core-concepts/config.zh.md

@@ -2,19 +2,19 @@
 
 DevStream使用 YAML 文件来声明 DevOps 工具链的配置。
 
-## 配置内容
+## 1 配置内容概览
 
 正如概述中所提到的，配置包含了以下几个部分：
 
 - `config`
-- `vars`
 - `tools`
 - `apps`
 - `pipelineTemplates`
+- `vars`
 
 其中，`config` 必选，`tools` 和 `apps` 至少有一个不为空，其余部分可选。
 
-## 组织方式
+## 2 组织方式
 
 DevStream 支持两种组织配置的方式：
 
@@ -28,11 +28,21 @@ DevStream 支持两种组织配置的方式：
 - 单文件：`dtm init -f config.yaml`
 - 目录：`dtm init -f dirname`
 
-## 主配置
+## 3 配置内容详解
+
+### 3.1 主配置
 
 指 DevStream 本身的配置，即 `config` 部分，比如状态存储的方式等。详见 [这里](./state.zh.md)
 
-## 变量语法
+### 3.2 工具的配置
+
+`tools` 部分声明了工具链中的工具，详见 [这里](./tools.zh.md)
+
+### 3.2 应用与流水线模板的配置
+
+`apps` 部分声明了 应用 的配置，`pipelineTemplates` 声明了 流水线模板，详见 [这里](./apps.zh.md)
+
+### 3.3 变量
 
 DevStream 提供了变量语法。使用 `vars` 用来定义变量的值，而后可以在 `tools`、`apps`、`pipelineTemplates` 中使用，语法是 `[[ varName ]]`。
 
@@ -56,10 +66,94 @@ tools:
     # <后面略...>
 ```
 
-## 工具的配置
+## 4 拓展语法
 
-`tools` 部分声明了工具链中的工具，详见 [这里](./tools.zh.md)
+### 4.1 环境变量
 
-## 应用与流水线模板的配置
+类似于"变量"，你可以使用 `[[env "env_key"]]` 的方式来引用环境变量。
+
+### 4.2 输出(Output)
+
+#### 介绍
+
+在 DevStream 的配置文件中，我们在配置 工具 的 Options 时，可以使用其他 工具 的 输出 来填充。
+
+例如，如果 工具 A 有一个输出，我们可以将这个输出值作为 工具 B 的 Options。
+
+注意：
+
+- 当前，若 B 使用了 A 的输出，并不意味着 B "依赖于" A
+- 如果 B 确实需要 "依赖于" A，即，我们想要保证在 B 运行之前行运行 A，我们仍然需要使用 `dependsOn` 关键字（详见上一节 "[核心概念](overview.zh.md)")。
+
+#### 语法
+
+我们可以通过以下格式来使用插件输出：
+
+```
+${{ TOOL_NAME.TOOL_INSTANCE_ID.outputs.OUTPUT_KEY }}
+```
+
+例如，对于下面给定的配置：
+
+```yaml
+tools:
+- name: trello
+  instanceID: default
+  options:
+    owner: IronCore864
+    repo: golang-demo
+    kanbanBoardName: golang-demo-board
+```
+
+- `TOOL_NAME` 是 "trello"
+- `TOOL_INSTANCE_ID` 是 "default"
+
+如果 "trello" 这个 工具 有一个键为 "boardId" 的输出项，那么我们就能通过以下语法来引用对应的输出的值：
+
+```
+${{ trello.default.outputs.boardId }}
+```
+
+#### 例子——真实使用场景
+
+配置如下：
+
+```yaml hl_lines="2 3 20 31"
+tools:
+- name: repo-scaffolding
+  instanceID: golang-github
+  options:
+    destinationRepo:
+      owner: IronCore864
+      name: golang-demo
+      branch: main
+      scmType: github
+    vars:
+      imageRepo: "ironcore864/golang-demo"
+    sourceRepo:
+      org: devstream-io
+      name: dtm-scaffolding-golang
+      scmType: github
+- name: helm-installer
+  instanceID: argocd
+- name: argocdapp
+  instanceID: default
+  dependsOn: [ "helm-installer.argocd", "repo-scaffolding.golang-github" ]
+  options:
+    app:
+      name: golang-demo
+      namespace: argocd
+    destination:
+      server: https://kubernetes.default.svc
+      namespace: default
+    source:
+      valuefile: values.yaml
+      path: helm/golang-demo
+      repoURL: ${{ repo-scaffolding.golang-github.outputs.repoURL }}
+```
+
+在这个例子中，
+
+- `argocdapp` 的 "default" 实例依赖于 `repo-scaffolding` 的 "golang-github" 实例
+- `argocdapp` 的 "default" 实例中有一个 options 是 "options.source.repoURL"，它引用了 `repo-scaffolding` 的 "golang-github" 实例的 "repoURL" 输出(`${{ repo-scaffolding.golang-github.outputs.repoURL }}`)。
 
-`apps` 部分声明了 应用 的配置，`pipelineTemplates` 声明了 流水线模板，详见 [这里](./apps.zh.md)