Skip to main content
版本: 0.6

文档生成工具

KCL 命令行工具支持从 KCL 源码中一键提取模型文档,并支持丰富的输出格式:JSON,YAML 和 Markdown 等。本文介绍 KCL 语言的文档规范,举例说明如何使用 KCL 文档生成工具提取文档,并展示新增本地化语言文档的流程。

1. KCL 语言的文档规范

KCL文件的文档主要包含如下两个部分:

  • 当前 KCL Moudle 的文档:对当前 KCL 文件的说明
  • KCL 文件内包含的所有 Schema 的文档:对当前 Schema 的说明,其中包含 Schema 描述、Schema 各属性的描述、Examples 三部分,具体格式如下:
  1. Schema 描述
"""这是Schema一个简短的描述信息
"""
  1. Schema 各属性的描述:包含属性描述、属性类型、默认值、是否可选
"""
Attributes
----------
x : type, default is a, optional.
Description of parameter `x`.
y : type, default is b, required.
Description of parameter `y`.
"""

其中,使用 ---------- 表示 Attributes 为一个标题(- 符号长度与标题长度保持一致),属性名称与属性类型用冒号 : 分隔,属性的说明另起一行并增加缩进进行书写。属性的默认值说明跟在属性类型之后使用逗号 , 分隔,书写为 default is {默认值} 形式,此外需要说明属性是否为可选/必选,对于可选属性在默认值之后书写 optional,对于必选属性在默认值之后书写 required

  1. Examples
"""
Examples
--------
val = Schema {
name = "Alice"
age = 18
}
"""

此外,KCL 文档字符串语法应采用 re-structured text (reST) 语法子集,并使用 Sphinx 渲染呈现。

2. 从 KCL 源码生成文档

使用 kcl-doc generate 命令,从用户指定的文件或目录中提取文档,并输出到指定目录。

  1. 参数说明
usage: kcl-doc generate [-h] [--format YAML] [-o OUTPUT] [--r]
[--i18n-locale LOCALE] [--repo-url REPO_URL]
[files [files ...]]

positional arguments:
files KCL file paths. If there's more than one files to
generate, separate them by space

optional arguments:
-h, --help show this help message and exit
--format YAML Doc file format, support YAML, JSON and MARKDOWN.
Defaults to MARKDOWN
-o OUTPUT, --output-path OUTPUT
Specify the output directory. Defaults to ./kcl_doc
--r, -R, --recursive Search directory recursively
--i18n-locale LOCALE I18n locale, e.g.: zh, zh_cn, en, en_AS. Defaults to
en
--repo-url REPO_URL The source code repository url. It will be displayed in
the generated doc to link to the source code.
  1. 从指定的一个或多个文件中提取文档,并输出到指定目录
kcl-doc generate your_config.k your_another_config.k -o your_docs_output_dir
  1. 从指定目录内,递归地查找 KCL 源码文件,并提取文档
kcl-doc generate your_config_dir -r -o your_docs_output_dir
  1. 在生成文档时,指定源码仓库地址。一经指定,生成的文档中将包含指向源码文件的链接
kcl-doc generate your_config.k -o your_docs_output_dir --repo-url https://url/to/source_code

3. 新增本地化语言的文档

如前所示,默认情况下,文档生成工具提取的文档以源码 docstring 的内容为准,因而文档的语言随 docstring 编写语言而定。如果需要为源文件新增本地化语言的文档,则可以遵循按如下步骤:

  1. 初始化 i18n 配置文件。该步骤基于指定的 KCL 源码文件,生成相应的 i18n 配置文件,文件格式可选 JSON/YAML,默认为 YAML. 输出的配置文件名称将以指定的目标本地化方言结尾
kcl-doc init-i18n your_config.k --format JSON --i18n-locale your_target_locale
  1. 手动修改上述生成的 i18n 配置文件,使用目标语言修改配置中的 doc 字段

  2. 基于修改后的 i18n 配置,生成本地化语言的文档。工具将查找指定目标语言的 i18n 配置文件,并转化为最终的文档

kcl-doc generate your_config_dir --i18n-locale your_target_locale --format Markdown

接下来,通过一个小例子演示新增本地化语言文档的过程。

3.1 准备 KCL 源码文件,例如 server.k:

```python
schema Server:
"""Server is the common user interface for long-running
services adopting the best practice of Kubernetes.

Attributes
----------
workloadType : str, default is "Deployment", required
Use this attribute to specify which kind of long-running service you want.
Valid values: Deployment, CafeDeployment.
See also: k8s/core/v1/workload_metadata.k.
name : str, required
A Server-level attribute.
The name of the long-running service.
See also: k8s/core/v1/metadata.k.
labels : {str:str}, optional
A Server-level attribute.
The labels of the long-running service.
See also: k8s/core/v1/metadata.k.

Examples
----------------------
myCustomApp = AppConfiguration {
name = "componentName"
}
"""

workloadType: str = "Deployment"
name: str
labels?: {str: str}
```

3.2 从 server.k 得到初始化的 i18n 配置文件,例如希望为其增加中文文档,指定生成的配置文件格式为 YAML

```text
kcl-doc init-i18n server.k --format YAML --i18n-locale zh_cn
```

该命令将在当前目录下创建 kcl_doc 目录,并生成 i18n 配置文件 kcl_doc/i18n_server_zh_cn.yaml,其内容如下:

```yaml
name: server
relative_path: ./server.k
schemas:
- name: Server
doc: |
Server is the common user interface for long-running
services adopting the best practice of Kubernetes.
attributes:
- name: workloadType
doc: |
Use this attribute to specify which kind of long-running service you want.
Valid values: Deployment, CafeDeployment.
See also: k8s/core/v1/workload_metadata.k.
type:
type_str: str
type_category: BUILTIN
builtin_type: STRING
default_value: '"Deployment"'
is_optional: false
- name: name
doc: |
A Server-level attribute.
The name of the long-running service.
See also: k8s/core/v1/metadata.k.
type:
type_str: str
type_category: BUILTIN
builtin_type: STRING
is_optional: false
default_value: ''
- name: labels
doc: |
A Server-level attribute.
The labels of the long-running service.
See also: k8s/core/v1/metadata.k.
type:
type_str: '{str: str}'
type_category: DICT
dict_type:
key_type:
type_str: str
type_category: BUILTIN
builtin_type: STRING
value_type:
type_str: str
type_category: BUILTIN
builtin_type: STRING
is_optional: true
default_value: ''
examples: |
myCustomApp = AppConfiguration {
name = "componentName"
}
doc: ''
source_code_url: ''
```

3.3 修改初始化得到的 i18n 配置,将其中的 doc 字段修改为中文的描述,修改后的配置如下:

```yaml
name: server
relative_path: ./server.k
schemas:
- name: Server
doc: |
Server 模型定义了采用 Kubernetes 最佳实践的持续运行的服务的通用配置接口
attributes:
- name: workloadType
doc: |
workloadType 属性定义了服务的类型,是服务级别的属性。合法的取值有:Deployment, CafeDeployment.
另请查看:k8s/core/v1/workload_metadata.k.
type:
type_str: str
type_category: BUILTIN
builtin_type: STRING
default_value: '"Deployment"'
is_optional: false
- name: name
doc: |
name 为服务的名称,是服务级别的属性。
另请查看:k8s/core/v1/metadata.k.
type:
type_str: str
type_category: BUILTIN
builtin_type: STRING
is_optional: false
default_value: ''
- name: labels
doc: |
labels 为服务的标签,是服务级别的属性。
另请查看:k8s/core/v1/metadata.k.
type:
type_str: '{str: str}'
type_category: DICT
dict_type:
key_type:
type_str: str
type_category: BUILTIN
builtin_type: STRING
value_type:
type_str: str
type_category: BUILTIN
builtin_type: STRING
is_optional: true
default_value: ''
examples: |
myCustomApp = AppConfiguration {
name = "componentName"
}
doc: ''
source_code_url: ''
```

3.4 基于修改后的 i18n 配置,生成本地化语言的文档,执行如下命令,将输出中文的文档 kcl_doc/doc_server_zh_cn.md,命令及生成的文档内容如下:

```text
kcl-doc generate server.k --i18n-locale zh_cn --format Markdown
```

~~~markdown
# server
## Schema Server
Server 模型定义了采用 Kubernetes 最佳实践的持续运行的服务的通用配置接口

### Attributes
|Name and Description|Type|Default Value|Required|
|--------------------|----|-------------|--------|
|**workloadType**<br />workloadType 属性定义了服务的类型,是服务级别的属性。合法的取值有:Deployment, CafeDeployment.<br />另请查看:k8s/core/v1/workload_metadata.k.|str|"Deployment"|**required**|
|**name**<br />name 为服务的名称,是服务级别的属性。<br />另请查看:k8s/core/v1/metadata.k.|str|Undefined|**required**|
|**labels**<br />labels 为服务的标签,是服务级别的属性。<br />另请查看:k8s/core/v1/metadata.k.|{str: str}|Undefined|optional|
### Examples
```
myCustomApp = AppConfiguration {
name = "componentName"
}
```

<!-- Auto generated by kcl-doc tool, please do not edit. -->

~~~

4. 附录

1. 常见的 reST 概念

对于 reST 格式的文档,段落和缩进很重要,新段落用空白行标记,缩进即为表示输出中的缩进。可以使用如下方式表示字体样式:

  • *斜体*
  • **粗体**
  • ``等宽字体``

参考 reST 文档获得更多帮助。