Merge pull request #497 from kcl-lang/feat-missing-doc

feat: add missing 0.11.0 docs

Author: zong-zhe

VERSION

@@ -1 +1 @@
-0.10
+0.11

docs/reference/model/crypto.md

@@ -90,6 +90,18 @@ import crypto
 blake3 = crypto.blake3("ABCDEF")
 ```
 
+## fileblake3
+
+`fileblake3(filepath: str) -> str`
+
+Encrypt the string readed from file `filepath` using `BLAKE3` and the codec registered for encoding.
+
+```python
+import crypto
+
+blake3 = crypto.fileblake3("test.txt")
+```
+
 ## uuid
 
 `uuid() -> str`
@@ -113,3 +125,15 @@ import crypto
 
 sha = crypto.filesha256("test.txt")
 ```
+
+## filesha512
+
+`filesha512(filepath: str) -> str`
+
+Calculate the SHA512 hash of the file `filepath`.
+
+```python
+import crypto
+
+sha = crypto.filesha512("test.txt")
+```

i18n/zh-CN/docusaurus-plugin-content-docs/current/reference/model/crypto.md

@@ -90,6 +90,18 @@ import crypto
 blake3 = crypto.blake3("ABCDEF")
 ```
 
+## fileblake3
+
+`fileblake3(filepath: str) -> str`
+
+使用注册编码器和 `BLAKE3` 算法对从文件`filepath`读取出的内容进行加密。
+
+```python
+import crypto
+
+fileblake3 = crypto.fileblake3("test.txt")
+```
+
 ## uuid
 
 `uuid() -> str`
@@ -113,3 +125,15 @@ import crypto
 
 sha = crypto.filesha256("test.txt")
 ```
+
+## filesha512
+
+`filesha512(filepath: str) -> str`
+
+计算文件 `filepath` 的 SHA512 哈希。
+
+```python
+import crypto
+
+sha = crypto.filesha512("test.txt")
+```

i18n/zh-CN/docusaurus-plugin-content-docs/version-0.11/community/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "社区",
+  "position": 5
+}

i18n/zh-CN/docusaurus-plugin-content-docs/version-0.11/community/contribute/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "贡献指南",
+  "position": 4
+}

i18n/zh-CN/docusaurus-plugin-content-docs/version-0.11/community/contribute/contribute-code.md

@@ -0,0 +1,25 @@
+---
+sidebar_position: 2
+---
+
+# 如何贡献代码?
+
+欢迎参与 KCL 共建贡献完善代码、完善代码文档和测试，同时也欢迎通过 Issue 提供反馈。本文主要针对修改和完善已有的代码，如果是希望增加 KCL 语言特性请通过 KEP 流程提交。
+
+## 1. 代码和注释中的错别字
+
+如果只是修改代码和注释中的错别字，不涉及代码逻辑的调整，那么可以直接在 Github 克隆仓库后直接修改并提交 PR。需要注意的是尽量保持代码风格一致。
+
+## 2. 如何贡献 KCL 代码
+
+- 先确保本地测试环境正常
+- 修改代码并补充测试
+- 本地测试通过后提交 PR
+
+## 3. 如何贡献 VS Code 插件代码
+
+请参考 VS Code 插件仓库的相关文档
+
+## 4. 开发流程相关代码
+
+欢迎通过 Issue 和讨论组讨论。

i18n/zh-CN/docusaurus-plugin-content-docs/version-0.11/community/contribute/contribute-docs.md

@@ -0,0 +1,61 @@
+---
+sidebar_position: 1
+---
+
+# 如何贡献文档?
+
+本文主要针对已有的文档做局部修改。如果是投稿博客文章、添加新的文档或者调整文档目录结构请先联系团队成员。
+
+KCL 文档分为用户指南、开发文档、内部文档、参考手册和博客文章等，他们的区别如下：
+
+- 用户指南：对应使用文档，是让用户以最小的代价快速使用 KCL 工具完整工作，不要涉及太多的内部原理和实现
+- 开发文档：内部是怎么实现的，主要针对希望了解 KCL 原理和参与贡献和开发的同学
+- 内部文档：针对企业用户的一些内部场景定制的文档
+- 参考手册：KCL 语言、工具和 IDE 等全部特性的文档，内容覆盖最广但比较琐碎
+- 博客文章：没有特别的限制，可以是针对某些具体的场景、某些技术点或者是整体发展展望等分享文章
+
+在贡献不同类型的文档时，最好能够结合上面的定位对不同的内容做一些适当的裁剪，给读者最佳体验。
+
+## 1. 基本规范
+
+- 除标题外，内部小标题尽量带编号，便于阅读
+- 工具自动输出的文档需要由到源代码的链接，小标题可以不带编号
+- 尽量不要贴大段的代码（30行以内），代码最好给出文字解释和对应的参考链接
+- 有图有真相，但是不推荐过度复杂的架构图
+- 内部链接：采用 `/docs/user_docs/getting-started/intro` 绝对路径形式
+
+**标点和空格**
+
+- 在中文的文档中优先使用中文的标点
+- 中文和英文之间需要增加 1 个空格
+- 中文和数字之间需要增加 1 个空格
+- 中文使用全角标点，标点前后均不添加空格
+- 英文内容使用半角标点，标点后面加 1 个空格
+- 链接前后需要保留一个空格，但是段落开头和中文全角标点附近不用添加空格。
+
+**图片和资源文件名**
+
+- 文件名和目录名只能用数字、英文字母、下划线 `_` 和减号 `-` 组成
+- 当前文档的图片放在当前目录的 images 目录下
+- 矢量图片可以通过 [drawio 离线版](https://github.com/jgraph/drawio-desktop/releases) 绘制（并同时提交源文件），以 200% 分辨率导出 png 格式图片
+
+## 2. 使用文档内容的基本模式
+
+每个使用文档可以看作是一个相对完整的分享或博客文章（参考手册不再此类）。使用文档遵循以下模式组织内容：
+
+1. 概览：本文希望解决什么问题，达到什么效果，可以先放最终效果截图
+1. 依赖的环境：需要安装什么工具，并给出相关链接
+1. 引入本文构建资源的关系图或架构图
+   - 需要用到的 Konfig 模型，给出模型参考页面链接，以及对应的上游原始模型的文档链接
+1. 具体的操作步骤
+   - 尽量确保最小化代码，甚至可以刻意隐藏一些干扰代码，同时给出完整代码对应的链接
+   - 列出每个步骤命令的概要输出信息，并配以文字描述
+1. 给出测试方式
+   - 尽量采用社区通用的方式（比如kube、curl命令、或浏览器）测试
+   - 给出测试结果的截图（和开头呼应）
+1. 总结和展望
+   - 简单回顾当前操作的流程，以及一些可以展开的地方（可以给出一些链接）
+
+## 3. 测试和提交 PR
+
+先克隆文档仓库，本地通过 `npm run start` 和 `npm run build` 命令测试查看效果，确保可以正常浏览后提交 PR 即可。

i18n/zh-CN/docusaurus-plugin-content-docs/version-0.11/community/contribute/contribute.md

@@ -0,0 +1 @@
+# 贡献指南

i18n/zh-CN/docusaurus-plugin-content-docs/version-0.11/community/contribute/git-guideline.md

@@ -0,0 +1,132 @@
+# Git 提交指南
+
+本文介绍了 Git 提交变更时需要注意的事项，如果拒绝接受本文的内容会导致提交的变更无法被接受。
+
+## 1. 关于 issue
+
+在提交一个 issue 之前，请先查阅已经关闭的 issue ，也许在关闭的 issue 中已经存在合适的解决方案。
+
+如果没有找到合适的方案，我们提供了4种模版在创建 issue 的时候使用。
+
+- Bug Report : 发现了一个 Bug，可以通过 Bug Report 模版创建 issue 与我们联系。
+- Enhancement : 开发者对工具进行了增强，可以通过 Enhancement 模版创建 issue 来介绍增加的内容。
+- Feature Request : 在使用的过程中想要为工具增加某些新的特性或者功能，可以通过 Feature Request 模版创建 issue 来描述新特性。
+- Ask a Question : 如果有任何的疑问，可以通过 Ask a Question 模版来创建一个 issue 与我们联系。
+
+在选择合适的模版后，只需要填写模版上的要求填写的内容即可。如果在创建 issue 的时候发现没有模版，或者模版内容为空，可以通过微信群，钉钉群或者邮件向我们反馈这个问题。
+
+## 2. 关于 Git 分支
+
+要向 kcl-lang 贡献代码，您必须拥有一个 GitHub 帐户，以便您可以将代码推送到您自己的分支并创建拉取请求。我们推荐参考 [Angular 规范](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines) 为您自己的分支命名。
+推荐的格式如下：
+
+```
+{type}-{a_short_description}
+```
+
+分支名称主要包括两个字段，并通过 “-” 分割。其中：
+
+- {type} : 当前分支内容的类型。
+- {a_short_description}: 一个简短的描述，介绍这个分支的主要内容。
+
+e.g. 张三首先 Fork 仓库到自己账户下，然后创建对应名称 `zhangsan:fix-output-fmt-bug` 的分支（冒号之前是张三的账号），用于修复输出格式化 bug。
+
+## 3. 关于 Git Commit
+
+我们参考 [Commitizen](https://github.com/commitizen/cz-cli) 书写 Commit Message。
+
+```
+注: 如果直接使用 Commitizen 生成 Commit Message，需要注意因为 Commitizen
+是开发人员管理 commit 的工具，与项目本身无关联，因此由 Commitizen 生成的中间产物
+(如: node_modules 文件目录)可能没有在项目 .gitignore 文件中。
+
+您可以 git add {filename} 选择要提交的文件而忽视中间产物。
+或者您可以向 .gitignore 文件中添加如下内容而自动忽视中间产物：
+# commitizen
+package.json
+package-lock.json
+node_modules/*
+```
+
+如果手动编写 Commit Message，我们也建议采用 [Commitizen](https://github.com/commitizen/cz-cli) 的 commit message 格式。
+
+```
+{type} ( {component_or_file} ) {a_short_description}
+    {a_longer_description}
+    BREAKING CHANGE: {breaking_change_description}.
+    {linked issue}
+```
+
+其中主要包括6个字段：
+
+- {type} : 当前 commit 对应的分支的类型。
+- {component_or_file}: 当前 commit 改动的模块或者文件的名称。
+- {a_short_description}: 简短的描述介绍 commit 中的内容。
+- {a_longer_description}: 详细的描述用来介绍 commit 中的内容。
+- {breaking_change_description}: 如果 commit 中包含破环兼容性的改动，需要对兼容性改动产生的影响进行介绍。
+- {linked issue}: 与当前这个 commit 关联的 issue。
+
+其中 {breaking_change_description} 和 {linked issue} 如果 commit 中不包含破坏兼容性的改动和关联的 issue，可以省略。
+
+e.g. 张三在分支 `zhangsan:fix-output-fmt-bug` 中创建的 commit。
+
+```
+
+  fix(kcl-printer): fix an output format bug in kcl-printer
+
+  There is an output format bug in kcl-printer because ...,
+  So, The calling of method "XXX" is replaced by "HHHH"...,
+  ...
+
+  -- 如果没有破坏兼容性的改动和关联的 issue 可以省略下面内容。
+
+  BREAKING CHANGE: This change maybe cause .......
+
+  fix #123
+
+```
+
+## 4. 关于 pull request
+
+在提交一个 PR 之前，可能需要优先考虑以下几个问题:
+
+- 请先查阅已经关闭的 PR ，也许在已经关闭的 PR 中，可能存在已经完成的解决方案。
+- 我们建议在提交变更之前，提交一个对应的 issue 描述变更中将要解决的问题，并将变更对应的 PR 与 issue 关联。
+- 在向我们提交 PR 之后，请签署 [Contributor License Agreement (CLA)](#cla) ，如果拒绝签署，我们将无法接受 PR。
+- 请确保每次改动都创建了一个新的分支，并根据上文中提到的规范为分支命名。
+- 一次 PR 请不要超过两个 commit ，请将多余的 commit 通过 squash 压缩，并根据上文中提到的规范，编写 commit message 。
+- 我们提供了 [PR 模版](https://github.com/kcl-lang/.github/blob/main/.github/PULL_REQUEST_TEMPLATE.md)，只需要添加模版中要求的内容即可，如果在创建PR时发现没有模版或者模版内容为空，可以通过微信群，钉钉群或者邮件向我们反馈这个问题。
+
+我们建议PR的标题与分支名、commit message 风格保持一致：
+
+```
+{type} ( {component_name_or_file_name} ) :{a_short_description}
+```
+
+e.g. 张三为分支`fix/zhangsan/fix_output_fmt_bug`创建的PR名称。
+
+```
+fix(kcl-printer): fix an output format bug in kcl-printer.
+```
+
+## 5. 目前 type 支持的类型
+
+参考[Angular 规范](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines)，type 支持类型的类型如下:
+
+```
+- feat:     -- 添加了新的功能特性。
+- fix:      -- 进行了 Bug 的修复。
+- docs:     -- 进行了文档部分的修改。
+- style:    -- 对代码格式的修改，并不影响代码的功能，如：删除多余空格，代码缩进等。
+- refactor: -- 在不改变代码功能的基础上对代码进行了的重构。
+- perf:     -- 对代码进行了性能优化。
+- test:     -- 添加或者调整已有的测试用例。
+- build:    -- 对构建系统或者外部依赖库进行了调整。
+- ci:       -- 调整了 CI 的配置文件或者脚本。
+- chore:    -- 对源代码和测试文件之外其他部分的调整。
+- revert:   -- 对 commit 进行回滚。
+```
+
+## <a name="cla"></a> 6. Contributor License Agreement (CLA)
+
+在第一次向我们提交 PR 之后，在 PR 中的 CLA 检查将会失败并提示签署 CLA。您可以通过自己的账户之间在 PR 回复 "I have read the CLA Document and I hereby sign the CLA" 表示同意签署 CLA，然后手动重启失败的 CLA 检查 Action 即可。当 PR 被成功合并之后将会被锁定不能再修改。

i18n/zh-CN/docusaurus-plugin-content-docs/version-0.11/community/intro/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "简介",
+  "position": 1
+}

i18n/zh-CN/docusaurus-plugin-content-docs/version-0.11/community/intro/intro.md

@@ -0,0 +1,9 @@
+---
+sidebar_position: 1
+---
+
+# 社区
+
+欢迎来到 KCL 开源社区，每个人的参与都是所有开源项目健康成长的动力！有很多方法可以参与开源。每个人都可以通过提交PR（Pull Request）来创建问题或修复 bug、改进文档或修改代码，
+
+可以查看[社区](https://github.com/kcl-lang/community)并加入我们。