Version: 0.4.3

Docgen

The KCL Docgen tool supports extracting model documents from KCL source code and supports multiple output formats: JSON, YAML and Markdown. This article introduces the document specification of the KCL language, gives an example of how to use the KCL Docgen tool to extract documents, and shows the process of importing localization documents.

1. Document Specification of KCL

The documentation of the KCL file mainly contains the following two parts:

Current KCL Module document: description of the current KCL file
All schema documents contained in the KCL file: a description of the current schema, including schema description, schema attribute descriptions, and Examples. The specific format is as follows:

Schema description

"""This is a brief description of the Schema
"""

Description of each attribute of Schema: including attribute description, attribute type, default value, optional or required
```
"""
Attributes
----------
x : type, default is a, optional.
    Description of parameter `x`.
y : type, default is b, required.
    Description of parameter `y`.
"""
```
---------- indicates that Attributes is a title (the length of the symbol - is the same as the length of the title), the attribute name and attribute type are separated by a colon :, the description of the attribute is written on another line with indentation. The default value of the attribute is separated by a comma , after the attribute type, and it is written in the form of default is {default value}. In addition, it is necessary to indicate whether the attribute is optional/required. Write optional after the default value for an optional attribute, and write required after the default value for a required attribute.

Examples

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

In addition, the KCL docstring syntax should use a subset of the re-structured text (reST) and be rendered using the Sphinx.

2. Generating Documentation From KCL

Use the kcl-doc generate command to extract documentation from a user-specified file or directory and output it to the specified directory.

Args

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.

Extract documents from the file(s) and output them to the specified directory
```
kcl-doc generate your_config.k your_another_config.k -o your_docs_output_dir
```
From the specified directory, recursively find the KCL file(s) and extract the documentation
```
kcl-doc generate your_config_dir -r -o your_docs_output_dir
```
When generating documentation, specify the source code repository address. The generated documentation will contain links to source files
```
kcl-doc generate your_config.k -o your_docs_output_dir --repo-url https://url/to/source_code
```

3. Add Documentation for Localized Languages

As shown before, by default, the documentation extracted by the documentation generation tool is based on the content of the source docstring, and thus the language of the documentation depends on the language in which the docstring was written. If you need to add localized language documentation to the source file, you can follow the steps below:

Initialize the i18n configuration file. This step generates the corresponding i18n configuration file based on the specified KCL file. The file format can be JSON/YAML, and the default is YAML. The output profile name will end in the specified target localization language
```
kcl-doc init-i18n your_config.k --format JSON --i18n-locale your_target_locale
```
Modify the i18n configuration file and update each doc field in your locale language

Generate localized documents from the modified i18n configuration file

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

Next, a simple example is used to demonstrate the process of adding localized language documents.

3.1 Prepare the KCL file, such as server.k:

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 Get the initialized i18n configuration file from the server.k. For example, if you want to add Chinese documents to it, specify the format of the generated configuration file as YAML

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

This command will create the directory kcl_doc under the current directory and generate the i18n configuration file kcl_doc/i18n_server_zh_cn.yaml. Its contents are as follows:

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 Modify all the doc fields to the Chinese description. The modified configuration is as follows:

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 Based on the modified i18n configuration, generate documents in localized languages. Execute the following command to output the Chinese document kcl_doc/doc_server_zh_cn.md. The commands and the contents of the generated documents are as follows:

kcl-doc generate server.k --i18n-locale zh_cn --format 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. Appendix

1. Concept of reST

For documents in reST format, paragraphs and indentation are important, new paragraphs are marked with blank lines, and indentation is the indentation indicated in the output. Font styles can be expressed as follows:

*Italic*
**Bold**
``Monospaced``

Refer to reST for more information.

Docgen

1. Document Specification of KCL​

2. Generating Documentation From KCL​

3. Add Documentation for Localized Languages​

4. Appendix​

1. Concept of reST​

1. Document Specification of KCL

2. Generating Documentation From KCL

3. Add Documentation for Localized Languages

4. Appendix

1. Concept of reST