Skip to content

Commit

Permalink
feat: add kcl v0.7 cli reference documents
Browse files Browse the repository at this point in the history 
Signed-off-by: peefy <[email protected]>
  • Loading branch information
@Peefy
Peefy committed Nov 28, 2023
1 parent b6efc15 commit 31cf7e8
Show file tree
Hide file tree
Showing 83 changed files with 1,794 additions and 1,694 deletions.
310 changes: 73 additions & 237 deletions docs/tools/cli/kcl/docgen.md
View file
Original file line number Diff line number Diff line change
@@ -1,16 +1,16 @@
---
sidebar_position: 5
sidebar_position: 2
---

# Docgen
# Doc

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.
The KCL Document tool supports extracting model documents from KCL source code and supports to output Markdown, HTML and OpenAPI formats. This document introduces the document specification of the KCL language, gives an example of how to use the KCL Document tool to extract documents.

## 1. Document Specification of KCL
## 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
- 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:

1. Schema description
Expand Down Expand Up @@ -50,268 +50,104 @@ val = Schema {

In addition, the KCL docstring syntax should use a subset of the [re-structured text (reST)](https://docutils.sourceforge.io/rst.html) and be rendered using the [Sphinx](https://www.sphinx-doc.org/en/master/).

## 2. Generating Documentation From KCL
## 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.
Use the `kcl doc generate` command to extract documentation from a user-specified file or directory and output it to the specified directory.

1. Args
Generate Markdown document for current package with a `kcl.mod` file.

```
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.
```shell
kcl doc generate
```

Generate HTML document for current package

```shell
kcl doc generate --format html
```

2. Extract documents from the file(s) and output them to the specified directory
Generate Markdown document for specific package

```text
kcl-doc generate your_config.k your_another_config.k -o your_docs_output_dir
```shell
kcl doc generate --file-path <package path>
```

3. From the specified directory, recursively find the KCL file(s) and extract the documentation
Generate Markdown document for specific package to a `<target directory>`

```text
kcl-doc generate your_config_dir -r -o your_docs_output_dir
```shell
kcl doc generate --file-path <package path> --target <target directory>
```

4. When generating documentation, specify the source code repository address. The generated documentation will contain links to source files
## Appendix

```text
kcl-doc generate your_config.k -o your_docs_output_dir --repo-url https://url/to/source_code
```
### Concept of reST

## 3. Add Documentation for Localized Languages
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:

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:
- \*Italic\*
- \*\*Bold\*\*
- \`\`Monospaced\`\`

1. 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
Refer to [reST](https://docutils.sourceforge.io/rst.html) for more information.

```text
kcl-doc init-i18n your_config.k --format JSON --i18n-locale your_target_locale
```
## Args

2. Modify the i18n configuration file and update each doc field in your locale language
### kcl doc

3. Generate localized documents from the modified i18n configuration file
```shell
This command shows documentation for KCL package or symbol.

```text
kcl-doc generate your_config_dir --i18n-locale your_target_locale --format Markdown
```
Usage:
kcl doc [command]

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`:

```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 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

```text
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:

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

```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 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:

```text
kcl-doc generate server.k --i18n-locale zh_cn --format Markdown
```
Aliases:
doc, d

````markdown
# server
Examples:
# Generate document for current package
kcl doc generate


## Schema Server
Available Commands:
generate Generates documents from code and examples

Server 模型定义了采用 Kubernetes 最佳实践的持续运行的服务的通用配置接口
Flags:
-h, --help help for doc

### Attributes
Use "kcl doc [command] --help" for more information about a command.
```

| 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 |
### kcl doc generate

### Examples
```shell
Usage:
kcl doc generate [flags]

```
myCustomApp = AppConfiguration {
name = "componentName"
}
```
Aliases:
generate, gen, g

<!-- Auto generated by kcl-doc tool, please do not edit. -->
````
Examples:
# Generate Markdown document for current package
kcl doc generate

## 4. Appendix
# Generate Html document for current package
kcl doc generate --format html

### 1. Concept of reST
# Generate Markdown document for specific package
kcl doc generate --file-path <package path>

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:
# Generate Markdown document for specific package to a <target directory>
kcl doc generate --file-path <package path> --target <target directory>

- \*Italic\*
- \*\*Bold\*\*
- \`\`Monospaced\`\`

Refer to [reST](https://docutils.sourceforge.io/rst.html) for more information.
Flags:
--escape-html Whether to escape html symbols when the output format is markdown. Always scape when the output format is html. Default to false.
--file-path string Relative or absolute path to the KCL package root when running kcl-doc command from
outside of the KCL package root directory.
If not specified, the current work directory will be used as the KCL package root.
--format string The document format to generate. Supported values: markdown, html, openapi. (default "md")
-h, --help help for generate
--ignore-deprecated Do not generate documentation for deprecated schemas.
--target string If not specified, the current work directory will be used. A docs/ folder will be created under the target directory.
--template string The template directory based on the KCL package root. If not specified, the built-in templates will be used.
```
Loading

0 comments on commit 31cf7e8

Please sign in to comment.