Merge pull request #454 from zong-zhe/refactor-kpm-doc

refactor: refactored the documentation for kpm's interaction with Oci…

Author: Peefy

docs/user_docs/guides/package-management/4-how-to/10-kpm_git.md

@@ -0,0 +1,38 @@
+# Use an Git-based repository
+
+KCL package management tool supports saving and sharing KCL modules through the OCI registry and Git repository. This section will introduce how to integrate the KCL package management tool with the Git repository.
+
+kpm does not provide the interaction between login/logout/push/pull and Git repository because users can use Git command line tools to login, logout, push, pull and other functions during interaction with Git repository. kpm only provides the ability to add a Git repository as a dependency to the a KCL package.
+
+## Private Git Repository
+
+KCL package management tool depends on the Git tool in the local environment to interact with the Git repository. Therefore, before using the KCL package management tool, ensure the Git tool is installed in the local environment and the Git command can be found in the environment variable $PATH.
+
+More Details - [How to Install Git Tool](https://git-scm.com/downloads)
+
+KCL package management tool shares the same login credentials with the Git tool in the local environment. When you use the KCL package management tool to interact with a private Git repository, you need to check whether the Git tool can interact with the private Git repository normally. If you can successfully download the private Git repository using the `git clone` command, you can directly use the KCL package management tool without any login operation.
+
+More Details - [Download Private Repository Using Git](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository)
+
+## Add a Git Repository as a Dependency
+
+You can use `kcl mod add` to add a Git repository as a dependency to the KCL package. 
+
+Take `https://github.com/kcl-lang/konfig` as an example. The command is as follows:
+
+```shell
+kcl mod add git://github.com/kcl-lang/konfig --tag v0.4.0 # Add a Git repository with a tag
+kcl mod add git://github.com/kcl-lang/konfig --commit 78ba6e9 # Add a Git repository with a commit
+kcl mod add git://github.com/kcl-lang/konfig --branch main # Add a Git repository with a branch
+```
+
+The way shown above is to add a Git repository as a dependency with Https protocol. 
+You can also use the `ssh` protocol or some other protocols to add a Git repository as a dependency as follows:
+
+```shell
+kcl mod add --git https://github.com/kcl-lang/konfig --tag v0.4.0 # Add a Git repository with a tag and Https protocol
+kcl mod add --git https://github.com/kcl-lang/konfig --branch main # Add a Git repository with a branch and Https protocol
+kcl mod add --git ssh://github.com/kcl-lang/konfig --commit 78ba6e9 # Add a Git repository with a commit and ssh protocol
+```
+
+

docs/user_docs/guides/package-management/4-how-to/10-private_mod_repo.md

@@ -1,4 +1,4 @@
-# Support for OCI Registries
+# Use an OCI-based registry
 
 KCL package management tool supports saving and sharing KCL packages through OCI Registries.
 
@@ -25,15 +25,13 @@ You can adjust the registry and repository name of the OCI registry by the follo
 
 ### By environment variable
 
-You can adjust the configuration of OCI Registry by setting the three environment variables `KPM_REG`, `KPM_REGO`, and `OCI_REG_PLAIN_HTTP`.
+You can adjust the configuration of OCI Registry by setting the three environment variables `KPM_REG`, `KPM_REGO`.
 
 ```shell
 # set default registry
 export KPM_REG="ghcr.io"
 # set default repository
 export KPM_REPO="kcl-lang"
-# set support for 'http'
-export OCI_REG_PLAIN_HTTP=off
 ```
 
 ### By configuration file
@@ -46,7 +44,6 @@ The default content of the configuration file is as follows:
 {
   "DefaultOciRegistry": "ghcr.io",
   "DefaultOciRepo": "kcl-lang",
-  "DefaultOciPlainHttp": true
 }
 ```
 
@@ -184,6 +181,32 @@ For the example, the command is as follows:
 kcl mod pull oci://localhost:5001/test/MyPkg --tag v0.1.0
 ```
 
+### `kcl mod add` to add a KCL package from OCI registry as a dependency
+
+You can use `kcl mod add` to add a KCL package from the default OCI registry. KPM will automatically search for the kcl package from the OCI registry in `kpm.json`.
+
+```shell
+kcl mod add <package_name>:<package_version>
+```
+
+For the example, the command is as follows:
+
+```shell
+kcl mod add MyPkg:v0.1.0
+```
+
+Or, you can download a kcl package from the specified OCI registry url.
+
+```shell
+kcl mod add <oci_url>
+```
+
+For the example, the command is as follows:
+
+```shell
+kcl mod add oci://localhost:5001/test/MyPkg --tag v0.1.0
+```
+
 ### `kcl run` to compile a KCL package
 
 KCL package management tool can directly compile a kcl package through the url of OCI.

docs/user_docs/guides/package-management/4-how-to/9-kpm_oci.md

@@ -0,0 +1,33 @@
+# 使用 Git 仓库
+
+KCL 包管理工具支持通过 OCI registry 和 Git 仓库保存和分享 KCL 包。本文将介绍如何使用 KCL 包管理工具与私有 OCI registry 和 Git 仓库集成。由于 Git 命令行工具提供了登录/push/pull等功能，因此，KCL 包管理工具将不再提供同样的功能，KCL 包管理工具仅支持通过 `kcl mod add` 命令将 git 仓库添加为当前 KCL 包的三方库。
+
+## 私有 Git 仓库
+
+KCL 包管理工具依赖本地环境中的 Git 工具完成与 Git 仓库的交互。因此，在使用 KCL 包管理工具之前，确保本地环境中完成了 Git 工具的安装，并且在环境变量 $PATH 中能够找到 Git 命令。
+
+更多信息 - [如何安装 Git 工具](https://git-scm.com/downloads)
+
+KCL 包管理工具与本地环境中的 Git 工具公用一份登录凭证，当您使用 KCL 包管理工具与私有 Git 仓库交互时，您需要先检查 Git 工具能否正常与私有 Git 仓库交互。如果您使用 `git clone` 命令能够成功下载私有 Git 仓库，您可以直接使用 KCL 包管理工具而不需要进行任何登录操作。
+
+更多信息 - [使用 Git 下载私有仓库](https://docs.github.com/zh/repositories/creating-and-managing-repositories/cloning-a-repository)
+
+## 添加 Git 仓库作为一个三方库依赖
+
+你可以使用 `kcl mod add` 命令将 Git 仓库添加为当前 KCL 包的三方库依赖。
+
+以 `https://github.com/kcl-lang/konfig` 为例，命令如下：
+
+```shell
+kcl mod add git://github.com/kcl-lang/konfig --tag v0.4.0 # 添加一个带有 tag 的 Git 仓库
+kcl mod add git://github.com/kcl-lang/konfig --commit 78ba6e9 # 添加一个带有 commit 的 Git 仓库
+kcl mod add git://github.com/kcl-lang/konfig --branch main # 添加一个带有 branch 的 Git 仓库
+```
+
+如上所示的方式是使用 Https 协议将 Git 仓库添加为一个依赖。你也可以使用 `ssh` 协议或其他协议将 Git 仓库添加为一个依赖，如下所示：
+
+```shell
+kcl mod add --git https://github.com/kcl-lang/konfig --tag v0.4.0 # 添加一个带有 tag 的 Git 仓库和 Https 协议
+kcl mod add --git https://github.com/kcl-lang/konfig --branch main # 添加一个带有 branch 的 Git 仓库和 Https 协议
+kcl mod add --git ssh://github.com/kcl-lang/konfig --commit 78ba6e9 # 添加一个带有 commit 的 Git 仓库和 ssh 协议
+```

i18n/zh-CN/docusaurus-plugin-content-docs/current/user_docs/guides/package-management/4-how-to/10-kpm_git.md

@@ -1,4 +1,4 @@
-# 支持 OCI Registries
+# 使用 OCI Registries
 
 KCL 包管理工具支持通过 OCI Registries 保存和分享 KCL 包。
 
@@ -25,15 +25,13 @@ KCL 包管理工具默认使用 ghcr.io 保存 KCL 包。
 
 ### 通过环境变量
 
-你可以通过设置三个环境变量 KPM_REG、KPM_REGO 和 OCI_REG_PLAIN_HTTP 来调整配置。
+你可以通过设置三个环境变量 KPM_REG、KPM_REGO 来调整配置。
 
 ```shell
 # 设置默认仓库地址
 export KPM_REG="ghcr.io"
 # 设置默认仓库
 export KPM_REPO="kcl-lang"
-# 设置支持 'http'
-export OCI_REG_PLAIN_HTTP=off
 ```
 
 ### 通过配置文件
@@ -46,7 +44,6 @@ KCL 包管理工具的配置文件位于 `$KCL_PKG_PATH/.kpm/config/kpm.json`，
 {
   "DefaultOciRegistry": "ghcr.io",
   "DefaultOciRepo": "kcl-lang",
-  "DefaultOciPlainHttp": true
 }
 ```
 
@@ -185,6 +182,32 @@ kcl mod pull <oci_url>
 kcl mod pull oci://localhost:5001/test/MyPkg --tag v0.1.0
 ```
 
+### kcl mod add
+
+你可以使用 `kcl mod add` 从默认的 OCI registry 中添加一个 kcl 包作为当前 kcl 包的三方依赖。kpm 会自动从 `kpm.json` 中的 OCI registry 中寻找 kcl 包。
+
+```shell
+kcl mod add <package_name>:<package_version>
+```
+
+对于示例来说，命令如下：
+
+```shell
+kcl mod add MyPkg:v0.1.0
+```
+
+或者，你也可以从指定的 OCI registry url 中下载一个 kcl 包。
+
+```shell
+kcl mod add <oci_url>
+```
+
+对于示例来说，命令如下：
+
+```shell
+kcl mod add oci://localhost:5001/test/MyPkg --tag v0.1.0
+```
+
 ### kcl run
 
 KCL 可以直接通过 OCI 的 url 编译 kcl 包。

i18n/zh-CN/docusaurus-plugin-content-docs/current/user_docs/guides/package-management/4-how-to/10-mod_private_repo.md

@@ -0,0 +1,33 @@
+# 使用 Git 仓库
+
+KCL 包管理工具支持通过 OCI registry 和 Git 仓库保存和分享 KCL 包。本文将介绍如何使用 KCL 包管理工具与私有 OCI registry 和 Git 仓库集成。由于 Git 命令行工具提供了登录/push/pull等功能，因此，KCL 包管理工具将不再提供同样的功能，KCL 包管理工具仅支持通过 `kcl mod add` 命令将 git 仓库添加为当前 KCL 包的三方库。
+
+## 私有 Git 仓库
+
+KCL 包管理工具依赖本地环境中的 Git 工具完成与 Git 仓库的交互。因此，在使用 KCL 包管理工具之前，确保本地环境中完成了 Git 工具的安装，并且在环境变量 $PATH 中能够找到 Git 命令。
+
+更多信息 - [如何安装 Git 工具](https://git-scm.com/downloads)
+
+KCL 包管理工具与本地环境中的 Git 工具公用一份登录凭证，当您使用 KCL 包管理工具与私有 Git 仓库交互时，您需要先检查 Git 工具能否正常与私有 Git 仓库交互。如果您使用 `git clone` 命令能够成功下载私有 Git 仓库，您可以直接使用 KCL 包管理工具而不需要进行任何登录操作。
+
+更多信息 - [使用 Git 下载私有仓库](https://docs.github.com/zh/repositories/creating-and-managing-repositories/cloning-a-repository)
+
+## 添加 Git 仓库作为一个三方库依赖
+
+你可以使用 `kcl mod add` 命令将 Git 仓库添加为当前 KCL 包的三方库依赖。
+
+以 `https://github.com/kcl-lang/konfig` 为例，命令如下：
+
+```shell
+kcl mod add git://github.com/kcl-lang/konfig --tag v0.4.0 # 添加一个带有 tag 的 Git 仓库
+kcl mod add git://github.com/kcl-lang/konfig --commit 78ba6e9 # 添加一个带有 commit 的 Git 仓库
+kcl mod add git://github.com/kcl-lang/konfig --branch main # 添加一个带有 branch 的 Git 仓库
+```
+
+如上所示的方式是使用 Https 协议将 Git 仓库添加为一个依赖。你也可以使用 `ssh` 协议或其他协议将 Git 仓库添加为一个依赖，如下所示：
+
+```shell
+kcl mod add --git https://github.com/kcl-lang/konfig --tag v0.4.0 # 添加一个带有 tag 的 Git 仓库和 Https 协议
+kcl mod add --git https://github.com/kcl-lang/konfig --branch main # 添加一个带有 branch 的 Git 仓库和 Https 协议
+kcl mod add --git ssh://github.com/kcl-lang/konfig --commit 78ba6e9 # 添加一个带有 commit 的 Git 仓库和 ssh 协议
+```