doc generate error / 文档生成错误

[LinYunling]

Bug Report

Please answer these questions before submitting your issue. Thanks!

1. Minimal reproduce step (Required)

1. The schema define: schema ResourceModel: ''' Resource Model Definition

   Attributes
   ----------
   name: str, default is "", required.
       The name of resource.
   alias: str, default is "", optional.
       The alias name of resource.
   type: str, default is "PC", required.
       The type of resource.
   
   Examples
   ----------------------
   res = ResourceModel {
       name = "ServerA"
       alias = "My Computer"
       type = "PC"
   }

   ''' name: str alias: str type: str

   check: type in ["PC", "Notebook", "IPad", "SmartPhone"]

2. kcl doc generate

3. see the markdown file, the result is error.

2. What did you expect to see? (Required)

1. Attribute definitions should be sorted in the order.
2. The alias is optional, but required.

   3. What did you see instead (Required)

   like 2

   4. What is your KCL components version? (Required)

   0.9.0-beta.1

[Peefy]

Hello @LinYunling

The type of attribute alias is depended on the definition instead of the doc string. For example, if you write the definition with the optional op ?, the doc will generate the right the form.

schema ResourceModel:
    '''
    Resource Model Definition

    Attributes
    ----------
    name: str, default is "", required.
        The name of resource.
    alias: str, default is "", optional.
        The alias name of resource.
    type: str, default is "string", required.
        The type of resource.

    Examples
    ----------------------
    res = ResourceModel {
        name = "ServerA"
        alias = "My Computer"
        type = "PC"
    }
    '''
    name: str
    alias?: str # Note the `?` here.
    type: str

    check:
        type in ["PC", "Notebook", "IPad", "SmartPhone"]

[LinYunling]

Only the description is from comments ? May I define the sorting order of attributes?

[LinYunling]

The document is misleading.

[Peefy]

Only the description is from comments ? May I define the sorting order of attributes?

1. The doc use the required/optional attribute annotation defined in the schema e.g., alias?: str or alias: str
2. At present, it is not yet supported to do so, but we can implement it in the kcl doc tool using the line attribute defined in the KCL OpenAPI type https://github.com/kcl-lang/kcl-go/blob/main/pkg/spec/gpyrpc/gpyrpc.pb.go#L3749. Welcome to open a new Issue or PR to record or implement it.