[Feature] KCL doc tool: extract, generate document of KCL packages

[amyXia1994]

Feature Request

Users and Typical Scenarios

• Document creation & maintenance: Platform SRE
• Document review & consumption: Application SRE and developer

User story and Workflow

Command Line Interface

The kcl-doc command extracts and renders documentation files of KCL packages. It will provider 2 sub commands: generate, start:

kcl-doc:

# kcl-doc command
kcl-doc -h

Usage: [--version] [--help] <command> [<args>]
Available commands are:
                the generate command is run by default
    generate    generates documents from code and examples
    start       starts a document website locally

arguments:
    --version                        show version of this kcl-doc command line tool
    --help                           show this information

kcl-doc generate:

# kcl-doc generate command
kcl-doc generate -h
generates documents from code and examples
    --schema-path <ARG>              Relative or absolute file path to the KCL package root
                                     when running kcl-doc command from outside of the KCL package root directory.
                                     If not specified, docs of all the KCL models under the work directory will be generated.
    --ignore-deprecated <ARG>        Do not generate documentation for deprecated schemas                                      (default: "false")
    --format <ARG>                   The document format to generate. Supported values: markdown, html, openapi                                                 (default: "markdown")
    --target <ARG>                   The target directory to store the generated document files.                               (default: "")
                                     If not specified, the current work directory will be used.
                                     A docs/ folder will be created under the target directory

kcl-doc start:

# kcl-doc start command
kcl-doc start
starts a document website locally

Spec of KCL Package and Schema Docs

the KCL doc spec is detailed defined in: #156

Integrate with IDE

doc highlight

Attribute names, types and descriptions in docstring can be highlighted at the semantic level to improve docstring readability. Here's a good example:

Hover to see docs

When the cursor hovers over the schema name and Attribute name, the document is displayed:

package info
---
schema description
---
**attribute**: type
description
---
\`\`\`
Example
\`\`\`

Here's a good example:

Document preview

In the schema file toolbar, click the preview button to expand the preview format of the document. The preview view in Markdown format is loaded by default. Here's a good example:

Auto-Completion in writing docstring

When a docstring is added to the model, the scaffolding code in docstring format is automatically generated, and the <> is a placeholder to be filled by the user:

<schema_description>

Attributes
----------
attr_name: <attribute_description>

Examples
--------
<example_code>

When editing docstring, automatically complete the Attributes document in docstring format, as well as the Attributes/Examples chapter title, etc. :

1. Auto-complete attribute names: Attributes, triggered by newlines/English characters
2. Automatically completes Attribues & Examples Chapter title: In the first line of the chapter, it is triggered by the prefix of the newline/chapter name

Here's a demo:

Diagnose and error reporting

Model/attributes for a. missing documents; b. The document contains undefined attributes; c. If the document content does not match the attribute declaration, mark the error message and provide quick repair actions.
todo: The contents and quick repair actions of each type of error prompt need to be detailed and discussed in the design of the error prompt function.

Auto-Completion in writing config

When assigning a configuration value, the assignment expression, including schema expr and value of attribute entry, completes the code snippet, and displays the snippet across multiple lines using inline completion. The snippets in samples/docstring-examples can be used as a source of completed code snippets.

Here's a demo:

Go to definition & reference

Jump from the attribute name in the docstring to the attribute definition and vice versa.
A good example:

Integrate with Github/Gitlab Pipeline

Integrated CICD pipeline in the model library

1. Document validation: A subset of the functionality of kcl-lint action
2. Document synchronization: Generate documents and synchronize them to github page; Synchronize data to the specified webhook

Integrate with Kpm Registry

• kpm package doc auto sync: CICD pipeline

[amyXia1994]

• here are some known issues about doc gen cli: [kcl-doc] wrong hints of generate command  kcl#281
• optimizations on doc spec: [Enhancement] kcl doc gen: optimize the document format and styles #157
• integration with IDE: [Feature] docstring generating and auto-completing in LSP kcl#709