Generate doc from json schema #7275
Conversation
There was a problem hiding this comment.
I added some inline comments below. But here are two overall comments when looking at the docs
- Can we use some kind of heading tags for the different properties? Or at least the top-level properties.
- The reason for this is that it will be very useful to be able to link directly to a property, so we want to output headings with an
id="property_name"tag so we can get<url>#property_namelinks directly to the properties.
- The reason for this is that it will be very useful to be able to link directly to a property, so we want to output headings with an
- When properties have oneofs, the layout becomes quite flat and it can be difficult to find out what they relate to. I'm wondering if different sizes, spacing or indentation could somehow make this easier to read. Maybe headings for top level properties would be enough. For example, see this screenshot:
| // orderedMapToYAMLNode recursively converts an orderedmap.OrderedMap to a yaml.Node | ||
| // It treats keys starting with "_comment_" as comments. | ||
| func orderedMapToYAMLNode(m orderedmap.OrderedMap) (*yaml.Node, error) { | ||
| node := &yaml.Node{ | ||
| Kind: yaml.MappingNode, | ||
| } | ||
|
|
||
| var pendingComment string | ||
| for _, key := range m.Keys() { | ||
| value, _ := m.Get(key) | ||
|
|
||
| // Check if the key is a comment (starts with "_comment_") | ||
| if strings.HasPrefix(key, "_comment_") { | ||
| if strVal, ok := value.(string); ok { | ||
| pendingComment = strVal | ||
| } | ||
| continue | ||
| } |
There was a problem hiding this comment.
Is this a normal way of doing examples in JSON Schema? It seems a little hard to read/edit when looking in the JSON.
We don't necessarily need examples in the JSON schema itself. We can have them in separate example docs instead.
| ## Properties | ||
|
|
||
|
|
||
| **`type`** - _[string]_ - Refers to the resource type and must be `alert` _(required)_ | ||
|
|
||
| **`name`** - _[string]_ - Name is usually inferred from the filename, but can be specified manually. | ||
|
|
||
| **`refs`** - _[array of oneOf]_ - List of resource references, each as a string or map. | ||
|
|
||
| *option 1* - _[object]_ - An object reference with at least a `<name>` and `<type>`. | ||
|
|
||
| - **`type`** - _[string]_ - type of resource | ||
|
|
||
| - **`name`** - _[string]_ - name of resource _(required)_ | ||
|
|
||
| *option 2* - _[string]_ - A string reference like `<resource-name>` or `<type/resource-name>`. | ||
|
|
||
| **`dev`** - _[object]_ - Overrides properties in development | ||
|
|
||
| **`prod`** - _[object]_ - Overrides properties in production | ||
|
|
There was a problem hiding this comment.
Would it be possible to have the common properties in a separate ## Common properties section of each page?
| **`refs`** - _[array of oneOf]_ - List of resource references, each as a string or map. | ||
|
|
||
| *option 1* - _[object]_ - An object reference with at least a `<name>` and `<type>`. | ||
|
|
||
| - **`type`** - _[string]_ - type of resource | ||
|
|
||
| - **`name`** - _[string]_ - name of resource _(required)_ | ||
|
|
||
| *option 2* - _[string]_ - A string reference like `<resource-name>` or `<type/resource-name>`. |
There was a problem hiding this comment.
Can we make option 2 the only documented option in the schema? And keep option 1 as an internal implementation detail. Every time the feature has been used, we have used option 2.
| **`refresh`** - _[object]_ - Specifies the refresh schedule that Rill should follow to re-ingest and update the underlying data _(required)_ | ||
|
|
||
| - **`cron`** - _[string]_ - A cron expression that defines the execution schedule | ||
|
|
||
| - **`every`** - _[string]_ - Run at a fixed interval using a Go duration string (e.g., '1h', '30m', '24h'). See: https://pkg.go.dev/time#ParseDuration |
There was a problem hiding this comment.
Let's remove every from the docs – we're probably going to deprecate it, and always use cron
| ### clickhouse | ||
|
|
||
|
|
||
|
|
||
| **`connector`** - _[string]_ _(required)_ | ||
|
|
||
| **`path`** - _[string]_ - Path to the data source. | ||
|
|
||
| **`format`** - _[string]_ - Format of the data source (e.g., csv, json, parquet). | ||
|
|
||
| **`managed`** - _[boolean]_ - `true` means Rill will provision the connector using the default provisioner. `false` disables automatic provisioning. | ||
|
|
||
| **`dsn`** - _[string]_ - DSN(Data Source Name) for the ClickHouse connection | ||
|
|
||
| **`username`** - _[string]_ - Username for authentication | ||
|
|
||
| **`password`** - _[string]_ - Password for authentication | ||
|
|
||
| **`host`** - _[string]_ - Host where the ClickHouse instance is running | ||
|
|
||
| **`port`** - _[integer]_ - Port where the ClickHouse instance is accessible |
There was a problem hiding this comment.
The properties listed here are for type: connector, not type: model. Models have fields like sql: and output: incremental_strategy, etc.
| --- | ||
| note: GENERATED. DO NOT EDIT. | ||
| title: Explore Dashboard YAML |
There was a problem hiding this comment.
Just call the file explore.yaml – every file name should match the type: <name> identifier so it's predictable to link to
| --- | ||
| note: GENERATED. DO NOT EDIT. | ||
| title: New Project files | ||
| sidebar_position: 30 | ||
| --- | ||
| ## Overview |
There was a problem hiding this comment.
Can you call this YAML Syntax and the path docs/reference/yaml/index.md? So it doesn't conflict with the current "Project files" section
Closes #1640
Checklist: