From b8a5f492ab4573044beb7a4593b2bbf18cd7e6c5 Mon Sep 17 00:00:00 2001 From: peefy Date: Mon, 27 Nov 2023 21:40:03 +0800 Subject: [PATCH] chore: format all documents Signed-off-by: peefy --- Makefile | 4 ++++ .../index.md | 13 +++++++------ blog/2023-11-23-biweekly-newsletter/index.md | 17 ++++++++++++----- .../4-how-to/7-publish_pkg_to_ah.md | 5 +---- .../index.md | 12 ++++++------ .../2023-11-23-biweekly-newsletter/index.md | 7 +++++++ .../4-how-to/7-publish_pkg_to_ah.md | 7 ++++--- .../4-how-to/7-publish_pkg_to_ah.md | 7 ++++--- .../4-how-to/7-publish_pkg_to_ah.md | 5 +---- 9 files changed, 46 insertions(+), 31 deletions(-) diff --git a/Makefile b/Makefile index ef4c8c11..586c9527 100644 --- a/Makefile +++ b/Makefile @@ -35,6 +35,10 @@ check-link: version: npm run docusaurus docs:version $(shell cat VERSION) +.PHONY: test +fmt: + npm run format + .PHONY: test test: ./examples/test.sh diff --git a/blog/2023-11-20-search-k8s-module-on-artifacthub/index.md b/blog/2023-11-20-search-k8s-module-on-artifacthub/index.md index b9ae9757..2279b9b1 100644 --- a/blog/2023-11-20-search-k8s-module-on-artifacthub/index.md +++ b/blog/2023-11-20-search-k8s-module-on-artifacthub/index.md @@ -18,13 +18,14 @@ Therefore, we have leveraged the [ArtifactHub](https://artifacthub.io/) project ## Prerequisites - Install KCL: *https://kcl-lang.io/docs/user_docs/getting-started/install/* -+ Install kubectl: *https://kubernetes.io/docs/tasks/tools/#kubectl* -+ Install minikube: *https://minikube.sigs.k8s.io/docs/start/* + +* Install kubectl: *https://kubernetes.io/docs/tasks/tools/#kubectl* +* Install minikube: *https://minikube.sigs.k8s.io/docs/start/* Start minikube using the following command: ```shell -minikube start --cache-images=true +minikube start --cache-images=true ``` If the Ingress controller is not installed in your minikube, you can use the following command to install it: @@ -38,13 +39,13 @@ minikube addons enable ingress First, let's prepare a simple JavaScript application: ```js -const express = require('express'); +const express = require("express"); const app = express(); const port = 8080; // Define a route that responds to GET requests -app.get('/', (req, res) => { - res.send('Welcome to my web application!'); +app.get("/", (req, res) => { + res.send("Welcome to my web application!"); }); // Start the server diff --git a/blog/2023-11-23-biweekly-newsletter/index.md b/blog/2023-11-23-biweekly-newsletter/index.md index 13608a61..3f428195 100644 --- a/blog/2023-11-23-biweekly-newsletter/index.md +++ b/blog/2023-11-23-biweekly-newsletter/index.md @@ -20,10 +20,12 @@ This section will update the KCL language community's latest developments every Thank you to all contributors for their outstanding work over the past two weeks (11.09 - 11.23 2023). Here is an overview of the key content: **📦 Module Update** + - The number of KCL modules has been increased to **200+**, mainly adding validation modules related to `Pod`, `RBAC`, and reference documentation for Kubernetes 1.14-1.28. - Now we can search and browse the documentation and usage of all modules on the `Artifact Hub` website: _[https://artifacthub.io/packages/search?org=kcl&sort=relevance&page=1](https://artifacthub.io/packages/search?org=kcl&sort=relevance&page=1)_ **💬 Language Update** + - **Developer Experience** - Optimized syntax indentation check for configuration code blocks, no longer enforced as an error. - Support for using file path wildcards as compilation entry points. @@ -46,41 +48,46 @@ Thank you to all contributors for their outstanding work over the past two weeks - Added the update command to automatically update local dependencies: _[https://github.com/kcl-lang/kpm/pull/212](https://github.com/kcl-lang/kpm/pull/212)_ **💻 IDE Update** + - **Developer Experience** - Support the completion of external package dependency import statements added by package management tools. - **Bug Fixes** - Fixed the display position of undefined type errors for function parameters. **🏄 API Update** + - Added KCL Unit Testing API: _[https://github.com/kcl-lang/kcl/pull/904](https://github.com/kcl-lang/kcl/pull/904)_ - Added KCL Symbol Renaming API: _[https://github.com/kcl-lang/kcl/pull/890](https://github.com/kcl-lang/kcl/pull/890)_ **🔥 Architecture Upgrade** + - KCL has designed and reconstructed a new semantic model, as well as APIs that support nearest symbol lookup and symbol semantic information query. - IDE features such as autocomplete, definition, and hover have been migrated to the new semantic model, significantly reducing the difficulty and amount of code for IDE feature development. **🚀 Performance Improvement** + - The KCL compiler supports incremental parsing of syntax and incremental checking of semantics, significantly improving the performance of KCL compilation, build, and IDE plugin usage in most scenarios by **5-10 times**. ## Special Thanks The following are listed in no particular order: -+ Thanks to @cr7258 for his contributions to the KCL model library and KCL documentation 🙌 +- Thanks to @cr7258 for his contributions to the KCL model library and KCL documentation 🙌 - _[https://github.com/kcl-lang/kcl-lang.io/pull/203](https://github.com/kcl-lang/kcl-lang.io/pull/203)_ - _[https://github.com/kcl-lang/kcl-lang.io/pull/209](https://github.com/kcl-lang/kcl-lang.io/pull/209)_ - _[https://github.com/kcl-lang/kcl-lang.io/pull/210](https://github.com/kcl-lang/kcl-lang.io/pull/210)_ - _[https://github.com/kcl-lang/kcl-lang.io/pull/211](https://github.com/kcl-lang/kcl-lang.io/pull/211)_ - _[https://github.com/kcl-lang/modules/pull/67](https://github.com/kcl-lang/modules/pull/67)_ -- Thanks to @XiaoK29 for his contributions to the code architecture refactoring of hover and reference lookup features in the KCL IDE, as well as the KCL documentation 🙌 + +* Thanks to @XiaoK29 for his contributions to the code architecture refactoring of hover and reference lookup features in the KCL IDE, as well as the KCL documentation 🙌 - _[https://github.com/kcl-lang/kcl/pull/887](https://github.com/kcl-lang/kcl/pull/887)_ - _[https://github.com/kcl-lang/kcl/pull/899](https://github.com/kcl-lang/kcl/pull/899)_ - _[https://github.com/kcl-lang/kcl-lang.io/pull/205](https://github.com/kcl-lang/kcl-lang.io/pull/205)_ -- Thanks to @MeenuyD, @negz for their discussions and support regarding the integration of Crossplane KCL Composition Functions 🙌 +* Thanks to @MeenuyD, @negz for their discussions and support regarding the integration of Crossplane KCL Composition Functions 🙌 - _[https://github.com/kcl-lang/kcl/issues/885](https://github.com/kcl-lang/kcl/issues/885)_ -- Thanks to @kolloch for his valuable feedback on the Bazel KCL build rule script 🙌 +* Thanks to @kolloch for his valuable feedback on the Bazel KCL build rule script 🙌 - _[https://github.com/kcl-lang/rules_kcl/pull/2](https://github.com/kcl-lang/rules_kcl/pull/2)_ -- Thanks to @Yun Lu, @Even Solberg, @Prahalad Ramji, @Matt Gowie, @ddh, and @mouuii for their valuable feedback and discussions during the promotion and usage of KCL 🙌 +* Thanks to @Yun Lu, @Even Solberg, @Prahalad Ramji, @Matt Gowie, @ddh, and @mouuii for their valuable feedback and discussions during the promotion and usage of KCL 🙌 ## Featured Updates diff --git a/docs/user_docs/guides/package-management/4-how-to/7-publish_pkg_to_ah.md b/docs/user_docs/guides/package-management/4-how-to/7-publish_pkg_to_ah.md index 92549535..c43c74da 100644 --- a/docs/user_docs/guides/package-management/4-how-to/7-publish_pkg_to_ah.md +++ b/docs/user_docs/guides/package-management/4-how-to/7-publish_pkg_to_ah.md @@ -8,7 +8,6 @@ Before you submit your PR, there are a few things you need to consider carefully - All source code of KCL modules in `modules` are **public**, if you want your KCL module to be private, sorry we currently do not support it, you can try to solve this problem by building your own repository. - - If you want to publish your KCL module to `modules` and can be found on `AH`, **The version of your module is required, and the version number must comply with the definition of [semantic versioning](https://semver.org/)**, that is, the `version` field in the kcl.mod, and must comply with the definition of semantic versioning. ``` @@ -20,7 +19,6 @@ version = "0.0.1" # This field is required and it must comply with the definitio - **Once a version of a module is published, its content cannot be changed. We do not allow the content of a module to be changed without changing the module version**. That is, if you submit a PR, change the content of the KCL module, and you want everyone to be able to use the changes you made, then you must upgrade the version of your KCL module, i.e., change the `version` field in kcl.mod. If you encounter difficulties that require you to change the content of a certain version of the module, please raise an issue in the repository and contact us. - ## Quick Start In the next section, we will show you how to publish your module with a `helloworld` example. @@ -58,7 +56,7 @@ Currently, the directory structure of a valid KCL module that the repository can - README.md : A markdown file as the documentation for your module, this file is **optional**, **if you do not provide this file, it will not be displayed on artifacthub.io**. -- (*.k) kcl program files: The source code of your KCL program. +- (\*.k) kcl program files: The source code of your KCL program. ### Publish your module by PR @@ -146,4 +144,3 @@ description = "This is my module." ``` **At the same time, you cannot upload the same version module multiple times.** Once the version number of your module has been used, you will not be able to use this version number again. The only way to upload this module again is to upgrade the version number. - diff --git a/i18n/zh-CN/docusaurus-plugin-content-blog/2023-11-20-search-k8s-module-on-artifacthub/index.md b/i18n/zh-CN/docusaurus-plugin-content-blog/2023-11-20-search-k8s-module-on-artifacthub/index.md index 1362db9b..ff3e8d02 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-blog/2023-11-20-search-k8s-module-on-artifacthub/index.md +++ b/i18n/zh-CN/docusaurus-plugin-content-blog/2023-11-20-search-k8s-module-on-artifacthub/index.md @@ -26,7 +26,7 @@ tags: [KCL, Kubernetes, Modules, ArtifactHub] 使用以下命令启动 minikube ```shell -minikube start --cache-images=true +minikube start --cache-images=true ``` 如果您的 minikube 中没有安装 Ingress 控制器，您可以使用如下命令安装： @@ -35,18 +35,18 @@ minikube start --cache-images=true minikube addons enable ingress ``` -## HelloWorld 案例 +## HelloWorld 案例 首先，我们可以准备一个简单的 js 应用。 ```js -const express = require('express'); +const express = require("express"); const app = express(); const port = 8080; // 定义一个响应 GET 请求的路由 -app.get('/', (req, res) => { - res.send('欢迎来到我的Web应用程序！'); +app.get("/", (req, res) => { + res.send("欢迎来到我的Web应用程序！"); }); // 启动服务器 @@ -202,7 +202,7 @@ $ curl http://localhost:8080 欢迎来到我的 Web 应用程序！ ``` -如果您通过浏览器访问，您将会看到： +如果您通过浏览器访问，您将会看到： ![browser](/img/blog/2023-11-20-search-k8s-module-on-artifacthub/browser.png) diff --git a/i18n/zh-CN/docusaurus-plugin-content-blog/2023-11-23-biweekly-newsletter/index.md b/i18n/zh-CN/docusaurus-plugin-content-blog/2023-11-23-biweekly-newsletter/index.md index 769e07b8..3231ff1b 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-blog/2023-11-23-biweekly-newsletter/index.md +++ b/i18n/zh-CN/docusaurus-plugin-content-blog/2023-11-23-biweekly-newsletter/index.md @@ -20,10 +20,12 @@ tags: [KCL, Biweekly-Newsletter] 感谢所有贡献者过去两周 (2023 11.09 - 11.23) 的杰出工作，以下是重点内容概述 **📦 模型更新** + - KCL 模型数量新增至 **200 个**，主要新增与 `Pod`, `RBAC` 相关的校验模型及 Kubernetes 1.14-1.28 版本的模型参考文档 - 可以在 `Artifact Hub` 中搜索浏览到所有模型的文档及使用方式: _[https://artifacthub.io/packages/search?org=kcl&sort=relevance&page=1](https://artifacthub.io/packages/search?org=kcl&sort=relevance&page=1)_ **💬 语言更新** + - **体验改进** - 优化配置代码块的语法缩进检查，不再强制报错 - 支持通过文件路径通配符作为编译入口 @@ -32,6 +34,7 @@ tags: [KCL, Biweekly-Newsletter] - 修复 Schema 参数数量的检查 **🔧 工具链更新** + - **测试工具发布** - 支持使用 KCL 函数编写单元测试并使用工具执行测试 - 支持使用正则表达式过滤待测试用例 @@ -45,20 +48,24 @@ tags: [KCL, Biweekly-Newsletter] - 新增 update 命令用于自动更新本地依赖: _[https://github.com/kcl-lang/kpm/pull/212](https://github.com/kcl-lang/kpm/pull/212)_ **💻 IDE 更新** + - **体验改进** - 支持包管理工具引入的外部包依赖 import 语句补全 - **错误修复** - 修复函数参数未定义类型错误显示位置 **🏄 API 更新** + - 新增 KCL 单元测试 API: _[https://github.com/kcl-lang/kcl/pull/904](https://github.com/kcl-lang/kcl/pull/904)_ - 新增 KCL 符号重命名 API: _[https://github.com/kcl-lang/kcl/pull/890](https://github.com/kcl-lang/kcl/pull/890)_ **🔥 架构升级** + - KCL 设计并重构了新的语义模型以及支持最近符号查找和符号语义信息查询 API - IDE 补全，跳转和悬停等功能实现迁移至新语义模型，显著降低 IDE 功能开发难度和代码量 **🚀 性能提升** + - KCL 编译器支持语法增量解析以及语义增量检查，大部分场景提升 KCL 编译构建和 IDE 插件使用性能 **5-10 倍** ## 特别鸣谢 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/user_docs/guides/package-management/4-how-to/7-publish_pkg_to_ah.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/user_docs/guides/package-management/4-how-to/7-publish_pkg_to_ah.md index 7d43d910..4f6ae139 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/user_docs/guides/package-management/4-how-to/7-publish_pkg_to_ah.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/user_docs/guides/package-management/4-how-to/7-publish_pkg_to_ah.md @@ -52,13 +52,13 @@ version = "0.0.1" # 这个字段不可以为空，并且必须符合语义化版 - kcl.mod.lock : 自动生成的用来固定依赖版本的文件，这个文件**可选的**，不需要手动改动。 - artifacthub-pkg.yaml : 这个文件是**可选的**，因为我们的仓库目前通过 artifacthub 展示所有的包，通过 artifacthub-pkg.yaml 来配置您想要包的信息，这里我们采取的策略是**如果在您的包的 kcl.mod 文件所在目录中有一个名为 artifacthub-pkg.yaml 的配置文件，那么，我们将使用您提供 artifacthub-pkg.yaml 来展示您的包的信息，否则，我们将会使用一些默认的信息生成对应的 artifacthub-pkg.yaml 文件。** - README.md : 一个 markdown 文件作为您的包的文档，这个文件是**可选的**，**如果您不提供这个文件，artifacthub 上将不会展示您的包的文档。** -- (*.k) kcl program files: 您的 KCL 程序的源代码。 +- (\*.k) kcl program files: 您的 KCL 程序的源代码。 ### 通过 PR 发布您的包 #### 1. 下载代码仓库 -首先，您需要使用 git 将仓库 https://github.com/kcl-lang/modules 下载到您的本地 +首先，您需要使用 git 将仓库 https://github.com/kcl-lang/modules 下载到您的本地 ```shell git clone https://github.com/kcl-lang/modules --depth=1 @@ -107,7 +107,7 @@ echo "This is a kcl module named helloworld." >> helloworld/README.md git add . ``` -使用 `git commit -s` 命令提交您的包, 我们推荐您的 commit message 遵循 “publish module ” 的格式。 +使用 `git commit -s` 命令提交您的包, 我们推荐您的 commit message 遵循 “publish module ” 的格式。 ```shell git commit -m "publish module helloworld" -s @@ -126,6 +126,7 @@ git push - [如何创建 PR](https://docs.github.com/zh/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) ### 通过 PR 升级您的包 + 完成包的内容上传后，您可以通过 PR 升级您的包。 注意：**我们没有提供任何改变包的内容但是不改变版本号的升级策略。** 如果您想要升级您的包，并希望您升级后的包被展示在 AH 上，您需要修改您的包的版本号。即在 kcl.mod 文件的 module 章节中的 version 字段。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.7.0/user_docs/guides/package-management/4-how-to/7-publish_pkg_to_ah.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.7.0/user_docs/guides/package-management/4-how-to/7-publish_pkg_to_ah.md index 7d43d910..4f6ae139 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.7.0/user_docs/guides/package-management/4-how-to/7-publish_pkg_to_ah.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.7.0/user_docs/guides/package-management/4-how-to/7-publish_pkg_to_ah.md @@ -52,13 +52,13 @@ version = "0.0.1" # 这个字段不可以为空，并且必须符合语义化版 - kcl.mod.lock : 自动生成的用来固定依赖版本的文件，这个文件**可选的**，不需要手动改动。 - artifacthub-pkg.yaml : 这个文件是**可选的**，因为我们的仓库目前通过 artifacthub 展示所有的包，通过 artifacthub-pkg.yaml 来配置您想要包的信息，这里我们采取的策略是**如果在您的包的 kcl.mod 文件所在目录中有一个名为 artifacthub-pkg.yaml 的配置文件，那么，我们将使用您提供 artifacthub-pkg.yaml 来展示您的包的信息，否则，我们将会使用一些默认的信息生成对应的 artifacthub-pkg.yaml 文件。** - README.md : 一个 markdown 文件作为您的包的文档，这个文件是**可选的**，**如果您不提供这个文件，artifacthub 上将不会展示您的包的文档。** -- (*.k) kcl program files: 您的 KCL 程序的源代码。 +- (\*.k) kcl program files: 您的 KCL 程序的源代码。 ### 通过 PR 发布您的包 #### 1. 下载代码仓库 -首先，您需要使用 git 将仓库 https://github.com/kcl-lang/modules 下载到您的本地 +首先，您需要使用 git 将仓库 https://github.com/kcl-lang/modules 下载到您的本地 ```shell git clone https://github.com/kcl-lang/modules --depth=1 @@ -107,7 +107,7 @@ echo "This is a kcl module named helloworld." >> helloworld/README.md git add . ``` -使用 `git commit -s` 命令提交您的包, 我们推荐您的 commit message 遵循 “publish module ” 的格式。 +使用 `git commit -s` 命令提交您的包, 我们推荐您的 commit message 遵循 “publish module ” 的格式。 ```shell git commit -m "publish module helloworld" -s @@ -126,6 +126,7 @@ git push - [如何创建 PR](https://docs.github.com/zh/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) ### 通过 PR 升级您的包 + 完成包的内容上传后，您可以通过 PR 升级您的包。 注意：**我们没有提供任何改变包的内容但是不改变版本号的升级策略。** 如果您想要升级您的包，并希望您升级后的包被展示在 AH 上，您需要修改您的包的版本号。即在 kcl.mod 文件的 module 章节中的 version 字段。 diff --git a/versioned_docs/version-0.7.0/user_docs/guides/package-management/4-how-to/7-publish_pkg_to_ah.md b/versioned_docs/version-0.7.0/user_docs/guides/package-management/4-how-to/7-publish_pkg_to_ah.md index 92549535..c43c74da 100644 --- a/versioned_docs/version-0.7.0/user_docs/guides/package-management/4-how-to/7-publish_pkg_to_ah.md +++ b/versioned_docs/version-0.7.0/user_docs/guides/package-management/4-how-to/7-publish_pkg_to_ah.md @@ -8,7 +8,6 @@ Before you submit your PR, there are a few things you need to consider carefully - All source code of KCL modules in `modules` are **public**, if you want your KCL module to be private, sorry we currently do not support it, you can try to solve this problem by building your own repository. - - If you want to publish your KCL module to `modules` and can be found on `AH`, **The version of your module is required, and the version number must comply with the definition of [semantic versioning](https://semver.org/)**, that is, the `version` field in the kcl.mod, and must comply with the definition of semantic versioning. ``` @@ -20,7 +19,6 @@ version = "0.0.1" # This field is required and it must comply with the definitio - **Once a version of a module is published, its content cannot be changed. We do not allow the content of a module to be changed without changing the module version**. That is, if you submit a PR, change the content of the KCL module, and you want everyone to be able to use the changes you made, then you must upgrade the version of your KCL module, i.e., change the `version` field in kcl.mod. If you encounter difficulties that require you to change the content of a certain version of the module, please raise an issue in the repository and contact us. - ## Quick Start In the next section, we will show you how to publish your module with a `helloworld` example. @@ -58,7 +56,7 @@ Currently, the directory structure of a valid KCL module that the repository can - README.md : A markdown file as the documentation for your module, this file is **optional**, **if you do not provide this file, it will not be displayed on artifacthub.io**. -- (*.k) kcl program files: The source code of your KCL program. +- (\*.k) kcl program files: The source code of your KCL program. ### Publish your module by PR @@ -146,4 +144,3 @@ description = "This is my module." ``` **At the same time, you cannot upload the same version module multiple times.** Once the version number of your module has been used, you will not be able to use this version number again. The only way to upload this module again is to upgrade the version number. -