diff --git a/docs/community/release-policy/kcl.md b/docs/community/release-policy/kcl.md index 9ab7be6a6..dd8402920 100644 --- a/docs/community/release-policy/kcl.md +++ b/docs/community/release-policy/kcl.md @@ -30,4 +30,5 @@ The KCL project version release strategy is as follows: - Testing and Feedback: Before releasing the feature, allow some peers/users to try and test these new features through written documentation rather than oral descriptions. Receive feedback and make improvements. - Release and Announcements: Write Release Notes, PR articles, interpret scenarios and new features, and promote through various channels. -> Note: All the above information is public and should be made available for all community developers to participate, discuss, and contribute. +> **NOTE:** +> All the above information is public and should be made available for all community developers to participate, discuss, and contribute. diff --git a/docs/reference/lang/codelab/schema.md b/docs/reference/lang/codelab/schema.md index 25072e330..9ada66ffe 100644 --- a/docs/reference/lang/codelab/schema.md +++ b/docs/reference/lang/codelab/schema.md @@ -159,7 +159,7 @@ nginx = Deployment { ## 5. Write More Complex Logic in Schema -Suppose we have some schema logic, we can wrapper it into schema: +Suppose we have some schema logic, we can wrap it into a schema: ```python schema Deployment[priority]: @@ -426,7 +426,7 @@ schema Volume: hostPath: str ``` -Since the attributes defined by the schema are **required** by default, the verification that judges that the variable cannot be None/Undefined can be omitted. +Since the attributes defined by the schema are **required** by default, no check to ensure they are not `None`/`Undefined` is needed. ```python schema Volume: @@ -474,7 +474,7 @@ Stderr: Schema check is failed to check condition: regex.match(image, "^[a-zA-Z]+:\d+\.\d+\.\d+$"), "image name should be like 'nginx:1.14.2'" ``` -> The verification capability of KCL covers the verification defined by Openapi so that we can write any API verifications through KCL. +> The verification capability of KCL covers the verification defined by OpenAPI so that we can write any API verifications through KCL. ## 9. Create New Schema via Schema Inheritance @@ -485,7 +485,7 @@ Usually, schema Deployment will be used in multiple scenarios. We can directly u For example, we can use the Deployment schema as a basis, to define the nginx's base schema, and extend the definition in each scenario. -In this case, we define some commonly used attributes. Please note that we mark the name to be immutable with the 'final' keyword to prevent it from being overwritten. +In this case, we define some commonly used attributes. Please note that to prevent the attribut `name` from being overwritten as immutable by assigning its final value. ```python schema Nginx(Deployment): @@ -604,7 +604,8 @@ mixin PersistentVolumeClaimMixin for PVCProtocol: } ``` -> Note: for the `k8s.api.core.v1` import to work, we need to initialize a module and add the `k8s` module as a dependency: +> **NOTE:** +> For the `k8s.api.core.v1` import to work, we need to initialize a module and add the `k8s` module as a dependency: > > ```bash > kcl mod init diff --git a/docs/reference/lang/codelab/simple.md b/docs/reference/lang/codelab/simple.md index 0a8e60d20..589598771 100644 --- a/docs/reference/lang/codelab/simple.md +++ b/docs/reference/lang/codelab/simple.md @@ -108,8 +108,8 @@ image: nginx:1.14.2 service: my-service ``` -.. note:: -KCL has rich support of operators and string member functions, please read manual and specification for more details. +> **NOTE:** +> KCL has rich support of operators and string member functions, please read the manual and specification for more details. ## 4. Write Collections @@ -183,8 +183,8 @@ else: cpu = _cpu memory = _cpu * 2 _command = ["nginx"] # a list -_command = _command + ["-f", "file"] # Append items into command using + operator to contact two lists -command = [c.lower() for c in _command] # Take each element in the list to lowercase +_command = _command + ["-f", "file"] # Append items into command using + operator to concatenate two lists +command = [c.lower() for c in _command] # Convert each element in the list to lowercase _labels = { run = "my-nginx" if _env: diff --git a/docs/reference/lang/spec/kcl-spec.md b/docs/reference/lang/spec/kcl-spec.md index 26e22eea7..19eae9bc0 100644 --- a/docs/reference/lang/spec/kcl-spec.md +++ b/docs/reference/lang/spec/kcl-spec.md @@ -10,9 +10,9 @@ description: KCL Spec ### Keywords and reserved words -The following are the keywords of the KCL: +The following identifiers are used as reserved words, or keywords of the language, and cannot be used as ordinary identifiers. They must be spelled exactly as written here: -```python +``` True False None Undefined import and or in is not as if else elif for @@ -21,9 +21,9 @@ all any map filter lambda rule ``` -The following are reserved words for the KCL: +The following tokens are not used, but they are reserved as possible future keywords: -```python +``` pass return validate rule flow def del raise except try finally while from with yield @@ -32,13 +32,13 @@ global nonlocal struct class final ### Line comment -```python +``` # a comment ``` ### Operators -```python +``` + - * ** / // % << >> & | ^ < > ~ <= >= == != = @@ -48,7 +48,7 @@ global nonlocal struct class final ### Delimiters -```python +``` ( ) [ ] { } , : . ; @ ``` @@ -76,7 +76,7 @@ The following list of operators is ordered from **highest to lowest**: ## Grammar -KCL uses Python's [LarkParser](https://lark-parser.readthedocs.io/en/latest/) tool to describe the grammar, and the specification rules are as follows: +KCL uses the Python-based [LarkParser](https://lark-parser.readthedocs.io/en/latest/) tool to describe the grammar, and the specification rules are as follows: ```bnf //////////// KCL grammar //////////// diff --git a/docs/reference/lang/spec/lexical.md b/docs/reference/lang/spec/lexical.md index 8c85ee7b3..872681a1d 100644 --- a/docs/reference/lang/spec/lexical.md +++ b/docs/reference/lang/spec/lexical.md @@ -56,8 +56,7 @@ A physical line is a sequence of characters end with a line termination sequence To join multiple physical lines into one logical line, the `\` character can be used. The character should be the last none-space character in each physical line except the very last line. -> **note** -> +> **NOTE:** > Any character except the ASCII space, tab (`\t`) and formfeed (`\f`) is considered a none-space character. - A line ending in a backslash cannot carry a comment (, which will be introduced shortly afterwards). diff --git a/docs/reference/lang/spec/schema.md b/docs/reference/lang/spec/schema.md index 179d3a446..52f0f7f27 100644 --- a/docs/reference/lang/spec/schema.md +++ b/docs/reference/lang/spec/schema.md @@ -527,7 +527,7 @@ The result is a **dict**: { 'person': { 'name': { - 'firstName': 'Jhon', + 'firstName': 'John', 'lastName': 'Doe' } } @@ -640,7 +640,7 @@ The result is a **dict**: 'JohnDoe': { 'firstName': 'John' 'lastName': 'Doe' - 'fullName': 'John Doe' + 'fullName': 'John_Doe' 'subject': 'CS' } } diff --git a/docs/reference/lang/spec/variables.md b/docs/reference/lang/spec/variables.md index b3e1c539a..c6e2dbc73 100644 --- a/docs/reference/lang/spec/variables.md +++ b/docs/reference/lang/spec/variables.md @@ -36,7 +36,7 @@ spam = "ham" spam = "eggs" # Error: The immutability rule is violated! ``` -- A variable starts with the `_` character is mutable. +- A variable starting with the `_` character is mutable. ```python _spam diff --git a/docs/reference/xlang-api/wasm-api.md b/docs/reference/xlang-api/wasm-api.md index f07ec78c2..c7e8682e6 100644 --- a/docs/reference/xlang-api/wasm-api.md +++ b/docs/reference/xlang-api/wasm-api.md @@ -18,7 +18,8 @@ Install the dependency npm install buffer @wasmer/wasi @kcl-lang/wasm-lib ``` -> Note: buffer is required by @wasmer/wasi. +> **NOTE:** +> Buffer is required by @wasmer/wasi. Write the code @@ -43,7 +44,8 @@ main(); Here, we use `webpack` to bundle the website, the `webpack.config.js` config as follows. -> Note: This configuration includes necessary settings for @wasmer/wasi and other required plugins. +> **NOTE:**: +> This configuration includes necessary settings for @wasmer/wasi and other required plugins. ```js const HtmlWebpackPlugin = require("html-webpack-plugin"); diff --git a/docs/user_docs/concepts/package-and-module.md b/docs/user_docs/concepts/package-and-module.md index 284775680..a4fceb0c2 100644 --- a/docs/user_docs/concepts/package-and-module.md +++ b/docs/user_docs/concepts/package-and-module.md @@ -10,7 +10,8 @@ Within a **module**, KCL organizes files grouped by **package**. A package can b A KCL module contains a configuration laid out in a directory hierarchy. It contains everything that is needed to deterministically determine the outcome of a KCL configuration. The root of this directory is marked by containing a `kcl.mod` directory. The contents of this directory are mostly managed by the kcl tool such as `kpm`, etc. In that sense, `kcl.mod` is analogous to the `.git` directory marking the root directory of a repo, but where its contents are mostly managed by the git tool. Besides, a KCL module is the largest unit of the file organization, has a fixed location of all KCL files and dependencies. -> Note: The use of a KCL module e.g., `kcl.mod` is optional, but required if one wants to manage, distribute, share and reuse code with a semantic version. +> **NOTE:** +> The use of a KCL module e.g., `kcl.mod` is optional, but required if one wants to manage, distribute, share and reuse code with a semantic version. ### Creating a module @@ -140,7 +141,8 @@ kcl_cli_configs: kcl -Y kcl.yaml ``` -> Note: If we do not specify any input files for KCL, KCL will find the default `kcl.yaml` from the command line execution path to read the input file. Besides, if we tell KCL both the input files and the compilation setting file, KCL will take input files entered by the user as the final value. +> **NOTE:** +> If we do not specify any input files for KCL, KCL will find the default `kcl.yaml` from the command line execution path to read the input file. Besides, if we tell KCL both the input files and the compilation setting file, KCL will take input files entered by the user as the final value. ```bash # Whether the 'files' field is configured in `kcl.yaml` or not, the final value of input files is ["file1.k", "file2.k"] diff --git a/docs/user_docs/guides/ci-integration/1-github-actions.md b/docs/user_docs/guides/ci-integration/1-github-actions.md index c4a09c6e4..ad0c801e8 100644 --- a/docs/user_docs/guides/ci-integration/1-github-actions.md +++ b/docs/user_docs/guides/ci-integration/1-github-actions.md @@ -9,7 +9,8 @@ sidebar_label: Github Actions In the GitOps section, we have introduced how to integrate KCL with GitOps. In this section, we will continue to provide sample solutions for KCL and CI integrations. We hope to implement the end-to-end application development process by using containers, Continuous Integration (CI) for generation, and GitOps for Continuous Deployment (CD). In this scheme, we use a **Flask application** and **Github Actions** as examples. -> Note: You can use any containerized application and different CI systems such as **Gitlab CI**, **Jenkins CI**, etc. in this solution. +> **NOTE:** +> You can use any containerized application and different CI systems such as **Gitlab CI**, **Jenkins CI**, etc. in this solution. The overall workflow is as follows: diff --git a/docs/user_docs/guides/ci-integration/2-gitlab-ci.md b/docs/user_docs/guides/ci-integration/2-gitlab-ci.md index 124e9bd9f..e28b2d76f 100644 --- a/docs/user_docs/guides/ci-integration/2-gitlab-ci.md +++ b/docs/user_docs/guides/ci-integration/2-gitlab-ci.md @@ -9,7 +9,8 @@ sidebar_label: Gitlab CI In the GitOps section, we have introduced how to integrate KCL with GitOps. In this section, we will continue to provide sample solutions for KCL and CI integrations. We hope to implement the end-to-end application development process by using containers, Continuous Integration (CI) for generation, and GitOps for Continuous Deployment (CD). In this scheme, we use a **Flask application** and **Gitlab CI** as examples. -> Note: You can use any containerized application and different CI systems such as **Github Actions**, **Jenkins CI**, etc. in this solution. +> **NOTE:** +> You can use any containerized application and different CI systems such as **Github Actions**, **Jenkins CI**, etc. in this solution. The overall workflow is as follows: diff --git a/docs/user_docs/support/faq-kcl.md b/docs/user_docs/support/faq-kcl.md index 7091c0bdc..8d953a419 100644 --- a/docs/user_docs/support/faq-kcl.md +++ b/docs/user_docs/support/faq-kcl.md @@ -73,7 +73,8 @@ bob = Person { } ``` -> Note: All KCL variables can be assigned the null value `None` and the undefined value `Undefined`. +> **NOTE:** +> All KCL variables can be assigned the null value `None` and the undefined value `Undefined`. ## 3. What do some KCL variable names prefixed with `_` underscore mean? What's the difference between without the `_` underscore prefix? In what scenarios are they suitable for use? @@ -172,7 +173,8 @@ _args = [*_args, "end"] # Add elements "end" to the end of the list: ["a", "b", _args = ["start", *_args] # Add elements "start" to the head of the list: ["start", "a", "b", "x", "c", "end"] ``` -> Note: When the consecutive variables are `None/Undefined`, using `+` may cause an error, then we can use the list unpacking operator `*` or use the `or` operator to take the default value of the list to avoid null values judge. +> **NOTE:** +> When the consecutive variables are `None/Undefined`, using `+` may cause an error, then we can use the list unpacking operator `*` or use the `or` operator to take the default value of the list to avoid null values judge. ```python data1 = [1, 2, 3] @@ -383,7 +385,8 @@ success = True _result = "success" if success else "failed" ``` -> Note: When writing an if-elif-else block statement, pay attention to the colon `:` after the if condition and keep the indentation consistent. +> **NOTE:** +> When writing an if-elif-else block statement, pay attention to the colon `:` after the if condition and keep the indentation consistent. In addition, conditional expressions can also be written directly in a list or dict (the difference is that the value to be written in the if expression written in the structure is not a statement): @@ -964,7 +967,8 @@ employee: nationality: China ``` -> Note: KCL only allows schema single inheritance. +> **NOTE:** +> KCL only allows schema single inheritance. ## 24. How to reuse schema logic through composition? @@ -1037,7 +1041,8 @@ import ..service # Relative path import, parent directory import ...root # Relative path import, parent directory of parent directory ``` -> Note that for KCL's entry file `main.k`, it cannot import the folder where it is located, otherwise a circular import error will occur: +> **NOTE:** +> For KCL's entry file `main.k`, it cannot import the folder where it is located, otherwise a circular import error will occur: ```python import model # Error: recursively loading @@ -1122,7 +1127,8 @@ The continue second line\ """ ``` -Note: Use the line continuation character `\` while maintaining indentation, as follows: +> **NOTE:** +> Use the line continuation character `\` while maintaining indentation, as follows: - Error use case: @@ -1192,7 +1198,8 @@ theFirstItem = data[0] # Get the element with index 0 in the list, that is, the theSecondItem = data[1] # Get the element with index 1 in the list, which is the first element 2 ``` -> Note: The value of the index cannot exceed the length of the list, otherwise an error will occur, we can use the `len` function to get the length of the list. +> **NOTE:** +> The value of the index cannot exceed the length of the list, otherwise an error will occur, we can use the `len` function to get the length of the list. ```python data = [1, 2, 3] @@ -1271,7 +1278,8 @@ data2 = data["contains.dot"] # "value3" # Note that this is wrong: data3 = data.contains.dot ``` -> Note: The above sub-element operators cannot operate on values of non-list/dict/schema collection types, such as integers, nulls, etc. +> **NOTE:** +> The above sub-element operators cannot operate on values of non-list/dict/schema collection types, such as integers, nulls, etc. ```python data = 1 @@ -1363,7 +1371,8 @@ if: 1 else: s ``` -> Note: Prefixing non-keyword identifiers with `$` has the same effect as not adding. +> **NOTE:** +> Prefixing non-keyword identifiers with `$` has the same effect as not adding. ```python _a = 1 @@ -1386,7 +1395,8 @@ int: 1 str: 2 ``` -> Note: If there are no special requirements, it is not recommended that the names of variables take these built-in types, because in some languages, they exist as keywords. +> **NOTE:** +> If there are no special requirements, it is not recommended that the names of variables take these built-in types, because in some languages, they exist as keywords. ## 33. How to implement enumeration in KCL? @@ -1564,7 +1574,8 @@ data = { # The merged writing order of the same attribute labels does not affect } # The final data value is {"labels": {"key1": "value1", "key2": "value2"}} ``` -Note: The merge attribute operator will check the merged values ​​for conflicts, and report an error when the configuration values ​​that need to be merged conflict. +> **NOTE:** +> The merge attribute operator will check the merged values for conflicts and report an error when the configuration values that need to be merged conflict. ```python data = { diff --git a/docs/user_docs/support/faq-yaml.md b/docs/user_docs/support/faq-yaml.md index b13a0f7ab..366c5ca69 100644 --- a/docs/user_docs/support/faq-yaml.md +++ b/docs/user_docs/support/faq-yaml.md @@ -17,7 +17,8 @@ string2: 'here''s to "quotes"' string3: here's to "quotes" ``` -> Note: KCL's strategy for outputting YAML strings is to output unquoted strings or double-quoted strings preferentially when single quotes appear in the string content, and output single-quoted strings in other cases to avoid the burden of understanding. +> **NOTE:** +> KCL's strategy for outputting YAML strings is to output unquoted strings or double-quoted strings preferentially when single quotes appear in the string content, and output single-quoted strings in other cases to avoid the burden of understanding. For more details, please refer to [YAML Spec v1.2](https://yaml.org/spec/1.2.1/)