Skip to content

Commit 08f70ca

Browse files
PeefyPeefy
authored
Merge pull request #222 from Peefy/cli-0.7-reference-documents
feat: add kcl v0.7 cli reference documents
2 parents bc5463f + bf5abd3 commit 08f70ca

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

86 files changed

+1790
-1834
lines changed

‎docs/tools/cli/kcl/docgen.md‎

Lines changed: 73 additions & 237 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,16 @@
11
---
2-
sidebar_position: 5
2+
sidebar_position: 2
33
---
44

5-
# Docgen
5+
# Doc
66

7-
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.
7+
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.
88

9-
## 1. Document Specification of KCL
9+
## Document Specification of KCL
1010

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

13-
- Current KCL Module document: description of the current KCL file
13+
- Current KCL module document: description of the current KCL file
1414
- 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:
1515

1616
1. Schema description
@@ -50,268 +50,104 @@ val = Schema {
5050

5151
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/).
5252

53-
## 2. Generating Documentation From KCL
53+
## Generating Documentation From KCL
5454

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

57-
1. Args
57+
Generate Markdown document for current package with a `kcl.mod` file.
5858

59-
```
60-
usage: kcl-doc generate [-h] [--format YAML] [-o OUTPUT] [--r]
61-
[--i18n-locale LOCALE] [--repo-url REPO_URL]
62-
[files [files ...]]
63-
64-
positional arguments:
65-
files KCL file paths. If there's more than one files to
66-
generate, separate them by space
67-
68-
optional arguments:
69-
-h, --help show this help message and exit
70-
--format YAML Doc file format, support YAML, JSON and MARKDOWN.
71-
Defaults to MARKDOWN
72-
-o OUTPUT, --output-path OUTPUT
73-
Specify the output directory. Defaults to ./kcl_doc
74-
--r, -R, --recursive Search directory recursively
75-
--i18n-locale LOCALE I18n locale, e.g.: zh, zh_cn, en, en_AS. Defaults to
76-
en
77-
--repo-url REPO_URL The source code repository url. It will be displayed in
78-
the generated doc to link to the source code.
59+
```shell
60+
kcl doc generate
61+
```
62+
63+
Generate HTML document for current package
64+
65+
```shell
66+
kcl doc generate --format html
7967
```
8068

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

83-
```text
84-
kcl-doc generate your_config.k your_another_config.k -o your_docs_output_dir
71+
```shell
72+
kcl doc generate --file-path <package path>
8573
```
8674

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

89-
```text
90-
kcl-doc generate your_config_dir -r -o your_docs_output_dir
77+
```shell
78+
kcl doc generate --file-path <package path> --target <target directory>
9179
```
9280

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

95-
```text
96-
kcl-doc generate your_config.k -o your_docs_output_dir --repo-url https://url/to/source_code
97-
```
83+
### Concept of reST
9884

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

101-
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:
87+
- \*Italic\*
88+
- \*\*Bold\*\*
89+
- \`\`Monospaced\`\`
10290

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

105-
```text
106-
kcl-doc init-i18n your_config.k --format JSON --i18n-locale your_target_locale
107-
```
93+
## Args
10894

109-
2. Modify the i18n configuration file and update each doc field in your locale language
95+
### kcl doc
11096

111-
3. Generate localized documents from the modified i18n configuration file
97+
```shell
98+
This command shows documentation for KCL package or symbol.
11299

113-
```text
114-
kcl-doc generate your_config_dir --i18n-locale your_target_locale --format Markdown
115-
```
100+
Usage:
101+
kcl doc [command]
116102

117-
Next, a simple example is used to demonstrate the process of adding localized language documents.
118-
119-
3.1 Prepare the KCL file, such as `server.k`:
120-
121-
```python
122-
schema Server:
123-
"""Server is the common user interface for long-running
124-
services adopting the best practice of Kubernetes.
125-
126-
Attributes
127-
----------
128-
workloadType : str, default is "Deployment", required
129-
Use this attribute to specify which kind of long-running service you want.
130-
Valid values: Deployment, CafeDeployment.
131-
See also: k8s/core/v1/workload_metadata.k.
132-
name : str, required
133-
A Server-level attribute.
134-
The name of the long-running service.
135-
See also: k8s/core/v1/metadata.k.
136-
labels : {str:str}, optional
137-
A Server-level attribute.
138-
The labels of the long-running service.
139-
See also: k8s/core/v1/metadata.k.
140-
141-
Examples
142-
----------------------
143-
myCustomApp = AppConfiguration {
144-
name = "componentName"
145-
}
146-
"""
147-
148-
workloadType: str = "Deployment"
149-
name: str
150-
labels?: {str: str}
151-
```
152-
153-
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
154-
155-
```text
156-
kcl-doc init-i18n server.k --format YAML --i18n-locale zh_cn
157-
```
158-
159-
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:
160-
161-
```yaml
162-
name: server
163-
relative_path: ./server.k
164-
schemas:
165-
- name: Server
166-
doc: |
167-
Server is the common user interface for long-running
168-
services adopting the best practice of Kubernetes.
169-
attributes:
170-
- name: workloadType
171-
doc: |
172-
Use this attribute to specify which kind of long-running service you want.
173-
Valid values: Deployment, CafeDeployment.
174-
See also: k8s/core/v1/workload_metadata.k.
175-
type:
176-
type_str: str
177-
type_category: BUILTIN
178-
builtin_type: STRING
179-
default_value: '"Deployment"'
180-
is_optional: false
181-
- name: name
182-
doc: |
183-
A Server-level attribute.
184-
The name of the long-running service.
185-
See also: k8s/core/v1/metadata.k.
186-
type:
187-
type_str: str
188-
type_category: BUILTIN
189-
builtin_type: STRING
190-
is_optional: false
191-
default_value: ''
192-
- name: labels
193-
doc: |
194-
A Server-level attribute.
195-
The labels of the long-running service.
196-
See also: k8s/core/v1/metadata.k.
197-
type:
198-
type_str: '{str: str}'
199-
type_category: DICT
200-
dict_type:
201-
key_type:
202-
type_str: str
203-
type_category: BUILTIN
204-
builtin_type: STRING
205-
value_type:
206-
type_str: str
207-
type_category: BUILTIN
208-
builtin_type: STRING
209-
is_optional: true
210-
default_value: ''
211-
examples: |
212-
myCustomApp = AppConfiguration {
213-
name = "componentName"
214-
}
215-
doc: ''
216-
source_code_url: ''
217-
```
218-
219-
3.3 Modify all the `doc` fields to the Chinese description. The modified configuration is as follows:
220-
221-
```yaml
222-
name: server
223-
relative_path: ./server.k
224-
schemas:
225-
- name: Server
226-
doc: |
227-
Server 模型定义了采用 Kubernetes 最佳实践的持续运行的服务的通用配置接口
228-
attributes:
229-
- name: workloadType
230-
doc: |
231-
workloadType 属性定义了服务的类型，是服务级别的属性。合法的取值有：Deployment, CafeDeployment.
232-
另请查看：k8s/core/v1/workload_metadata.k.
233-
type:
234-
type_str: str
235-
type_category: BUILTIN
236-
builtin_type: STRING
237-
default_value: '"Deployment"'
238-
is_optional: false
239-
- name: name
240-
doc: |
241-
name 为服务的名称，是服务级别的属性。
242-
另请查看：k8s/core/v1/metadata.k.
243-
type:
244-
type_str: str
245-
type_category: BUILTIN
246-
builtin_type: STRING
247-
is_optional: false
248-
default_value: ''
249-
- name: labels
250-
doc: |
251-
labels 为服务的标签，是服务级别的属性。
252-
另请查看：k8s/core/v1/metadata.k.
253-
type:
254-
type_str: '{str: str}'
255-
type_category: DICT
256-
dict_type:
257-
key_type:
258-
type_str: str
259-
type_category: BUILTIN
260-
builtin_type: STRING
261-
value_type:
262-
type_str: str
263-
type_category: BUILTIN
264-
builtin_type: STRING
265-
is_optional: true
266-
default_value: ''
267-
examples: |
268-
myCustomApp = AppConfiguration {
269-
name = "componentName"
270-
}
271-
doc: ''
272-
source_code_url: ''
273-
```
274-
275-
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:
276-
277-
```text
278-
kcl-doc generate server.k --i18n-locale zh_cn --format Markdown
279-
```
103+
Aliases:
104+
doc, d
280105

281-
````markdown
282-
# server
106+
Examples:
107+
# Generate document for current package
108+
kcl doc generate
109+
283110

284-
## Schema Server
111+
Available Commands:
112+
generate Generates documents from code and examples
285113

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

288-
### Attributes
117+
Use "kcl doc [command] --help" for more information about a command.
118+
```
289119

290-
| Name and Description | Type | Default Value | Required |
291-
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------------- | ------------ |
292-
| **workloadType**<br />workloadType 属性定义了服务的类型，是服务级别的属性。合法的取值有：Deployment, CafeDeployment.<br />另请查看：k8s/core/v1/workload_metadata.k. | str | "Deployment" | **required** |
293-
| **name**<br />name 为服务的名称，是服务级别的属性。<br />另请查看：k8s/core/v1/metadata.k. | str | Undefined | **required** |
294-
| **labels**<br />labels 为服务的标签，是服务级别的属性。<br />另请查看：k8s/core/v1/metadata.k. | {str: str} | Undefined | optional |
120+
### kcl doc generate
295121

296-
### Examples
122+
```shell
123+
Usage:
124+
kcl doc generate [flags]
297125

298-
```
299-
myCustomApp = AppConfiguration {
300-
name = "componentName"
301-
}
302-
```
126+
Aliases:
127+
generate, gen, g
303128

304-
<!-- Auto generated by kcl-doc tool, please do not edit. -->
305-
````
129+
Examples:
130+
# Generate Markdown document for current package
131+
kcl doc generate
306132

307-
## 4. Appendix
133+
# Generate Html document for current package
134+
kcl doc generate --format html
308135

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

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

313-
- \*Italic\*
314-
- \*\*Bold\*\*
315-
- \`\`Monospaced\`\`
316142

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

0 commit comments

Comments
 (0)