[Enhancement]support an option to display schema attributes in a flatten way

Enhancement

Background

KCL focuses on model abstraction and configuration, and it's important to provide a clear overview of the attribute list and attribute details in the model documentation to both model maintainers and developers writing configurations based on the model.

The goal is to achieve that: With all information readily available in the doc, developers can write usable configurations without the need to navigate to other pages -- that requires all the configurable fields, along with their structures, constraints, and descriptions, can be obtained on a single page for the concerned model.

Design

Currently, the documentation generated by the KCL Doc tool only supports nested display of models, see konfig model docs on kusionstack.io.

flat(the way terraform registry adopted, example) and the nested representation, pros and cons:

flat representation: more complete information within a concentrated view. No need to navigate between pages.
nested representation: more concise schema structure, more independent schemas, less duplicate infos.

Solution

provide an option on whether to display schema attributes in a flattened or nested way.

NAME:
   kcl-go doc generate - generates documents from code and examples

USAGE:
   # Generate Markdown document for current package
   kcl-go doc generate

   # Generate Markdown document for specific package to a <target directory>
   kcl-go doc generate --file-path <package path> --target <target directory>

   # Generate Markdown document for specific package to a <target directory>. Display the schema attribute type in a flattened way
   kcl-go doc generate --file-path <package path> --target <target directory> --flatten

OPTIONS:
   --flatten                  Whether to display the schema attribute type in a flattened way. (default: false)

cc @ffforest

Here I uploaded a demo to demonstrate the appearance when displaying the schema attributes in a flattened way: https://github.com/amyXia1994/kusionstack.io/blob/demo/model-doc-style/docs/user_docs/reference/model/catalog_models/doc_app_configuration.md

After I saw this demo with all real models in the catalog repo, I think displaying attributes in a flattened way with markdown is not a good idea:

The nested hierarchy of frontend models can be quite deep. For example, the most frequently used AppConfiguration schema has a maximum nesting depth of 6 levels: AppConfiguration.workload.containers.livenessProbe.probeHandler.command. This means that when the attributes of AppConfiguration are expanded, its content will include varied documentation for models at 6 different levels. For users, viewing such a complex hierarchical structure is quite hard, and makes the flat representation less clear than a jump-based navigation.
There is a significant amount of reuse within the frontend models. This means that a flat representation would result in a lot of duplicated content, resulting in exposing users to lots of redundant information at the same time, and making it hard to focus on the most important infos (the first-level attribute list). For example, the Exec model in the given example is reused by 5 different attributes: livenessProbe.probeHandler, readinessProbe.probeHandler, startupProbe.probeHandler, lifecycle.preStop, lifecycle.postStart, and all of these attributes are indirectly located under one AppConfiguration model.
After flattening all the attributes, documents could be really long due to the combined, explosion effects of deep levels, ubiquitous schema reuse, and long attribute lists. I tried to collapse some details of the models, but the result is still unsatisfactory: Users need to expand all the levels to see the complete while complex document.

Research on similar documentation platforms:

Terraform Registry

Terraform registry adopts a flat representation more suitably, as the resources and data resources of TF usually have less level of attribute nesting and less model reuse than Kusion.

Pulumi Registry

The approach of Pulumi Registry is closer to the method we are currently adopting on kusionstack.io website.(Though kusionstack.io does not include all the related models on the AppConfiguration schema page)

Pulumi registry adopts a navigation representation of nested schemas. All the related schemas are organized in a fixed section - Supporting Types, so that all the related schemas are displayed on one page, and no duplication of reused schemas.

example: https://www.pulumi.com/registry/packages/grafana/api-docs/cloudaccesspolicy/

OpenAPI-based API management platform

They all adopted a flat representation. (I believe that was for the purpose of quickly validating RESTful APIs)

swagger editor: https://editor.swagger.io/ schemas all schemas and schema attribute details are flatten and by default collapsed
smartAPI: https://smart-api.info/ui/cd9fc0ca8cc6d9f56bd56a34766de791 similar with swagger editor, but with first-level attribute description, type info shown by default
spotlight: https://elements-demo.stoplight.io/?spec=https://api.apis.guru/v2/specs/instagram.com/1.0.0/swagger.yaml#/schemas/MediaSearchResponse one page for each schema, with first-level attribute details, and deeper attributes collapsed by default. The attributes are displayed with an explicit tree structure and indentation. Spotlight provides the clearest documentation among all the three platforms.

The Conclusion

Based on following facts:

A flattened representation like what spotlight does is complete, clear, focused, while requires CSS design.
A navigation representation is also concentrated and could be implemented with markdown.

Currently, we can continue the navigation way. Once our website and registry design are matured and we have more time to support the generation of HTML documentation, we can consider supporting the Spotlight way.

kcl-lang / kcl-go