apitech
/
grafana
mirror of https://github.com/grafana/grafana
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Codegen: Generate docs for composable kinds (#61719)

Browse Source 
* Generate docs for composable kinds

* Fix getting the kind schema

* Generate composable kinds docs

* Add disclaimer to the generated docs

* Change docs disclaimer
pull/61474/head
Tania 2 years ago committed by GitHub
parent 65127d4913
commit 5f93e67419
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
20 changed files with 483 additions and 4 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 8
      docs/sources/developers/kinds/composable/_index.md
  2. 37
      docs/sources/developers/kinds/composable/annotationslistpanelcfg/schema-reference.md
  3. 61
      docs/sources/developers/kinds/composable/barchartpanelcfg/schema-reference.md
  4. 31
      docs/sources/developers/kinds/composable/bargaugepanelcfg/schema-reference.md
  5. 37
      docs/sources/developers/kinds/composable/dashboardlistpanelcfg/schema-reference.md
  6. 29
      docs/sources/developers/kinds/composable/gaugepanelcfg/schema-reference.md
  7. 41
      docs/sources/developers/kinds/composable/histogrampanelcfg/schema-reference.md
  8. 29
      docs/sources/developers/kinds/composable/newspanelcfg/schema-reference.md
  9. 73
      docs/sources/developers/kinds/composable/piechartpanelcfg/schema-reference.md
  10. 31
      docs/sources/developers/kinds/composable/statpanelcfg/schema-reference.md
  11. 53
      docs/sources/developers/kinds/composable/textpanelcfg/schema-reference.md
  12. 1
      docs/sources/developers/kinds/core/dashboard/schema-reference.md
  13. 1
      docs/sources/developers/kinds/core/playlist/schema-reference.md
  14. 1
      docs/sources/developers/kinds/core/team/schema-reference.md
  15. 10
      pkg/codegen/jenny_docs.go
  16. 1
      pkg/codegen/tmpl/docs.tmpl
  17. 28
      pkg/plugins/codegen/jenny_plugindocs.go
  18. 1
      pkg/plugins/pfs/decl.go
  19. 1
      pkg/plugins/pfs/decl_parser.go
  20. 13
      public/app/plugins/gen.go

8
docs/sources/developers/kinds/composable/_index.md
Unescape View File

@ -0,0 +1,8 @@
---
title: Composable kinds
weight: 200
---
# Grafana composable kinds
{{< section >}}

37
docs/sources/developers/kinds/composable/annotationslistpanelcfg/schema-reference.md
Unescape View File

@ -0,0 +1,37 @@
---
keywords:
- grafana
- schema
title: AnnotationsListPanelCfg kind
---
> Both documentation generation and kinds schemas are in active development and subject to change without prior notice.
# AnnotationsListPanelCfg kind
### Maturity: experimental
### Version: 0.0
## Properties
| Property | Type | Required | Description |
|----------------|-------------------------|----------|-------------|
| `PanelOptions` | [object](#paneloptions) | **Yes** | |
## PanelOptions
### Properties
| Property | Type | Required | Description |
|-------------------------|----------|----------|-------------------|
| `limit` | integer | **Yes** | Default: `10`. |
| `navigateAfter` | string | **Yes** | Default: `10m`. |
| `navigateBefore` | string | **Yes** | Default: `10m`. |
| `navigateToPanel` | boolean | **Yes** | Default: `true`. |
| `onlyFromThisDashboard` | boolean | **Yes** | Default: `false`. |
| `onlyInTimeRange` | boolean | **Yes** | Default: `false`. |
| `showTags` | boolean | **Yes** | Default: `true`. |
| `showTime` | boolean | **Yes** | Default: `true`. |
| `showUser` | boolean | **Yes** | Default: `true`. |
| `tags` | string[] | **Yes** | |

61
docs/sources/developers/kinds/composable/barchartpanelcfg/schema-reference.md
Unescape View File

@ -0,0 +1,61 @@
---
keywords:
- grafana
- schema
title: BarChartPanelCfg kind
---
> Both documentation generation and kinds schemas are in active development and subject to change without prior notice.
# BarChartPanelCfg kind
### Maturity: experimental
### Version: 0.0
## Properties
| Property | Type | Required | Description |
|--------------------|-----------------------------|----------|-------------|
| `PanelFieldConfig` | [object](#panelfieldconfig) | **Yes** | |
| `PanelOptions` | [object](#paneloptions) | **Yes** | |
## PanelFieldConfig
### Properties
| Property | Type | Required | Description |
|-------------------|-----------------------------------------------------------|----------|--------------------------------------------------------------------|
| `fillOpacity` | integer | No | Controls the fill opacity of the bars. Default: `80`. |
| `gradientMode` | string | No | TODO docs Possible values are: `none`, `opacity`, `hue`, `scheme`. |
| `lineWidth` | integer | No | Controls line width of the bars. Default: `1`. |
| `thresholdsStyle` | [GraphThresholdsStyleConfig](#graphthresholdsstyleconfig) | No | TODO docs |
### GraphThresholdsStyleConfig
TODO docs
#### Properties
| Property | Type | Required | Description |
|----------|--------|----------|-------------------------------------------------------------------------------------------------------|
| `mode` | string | **Yes** | TODO docs Possible values are: `off`, `line`, `dashed`, `area`, `line+area`, `dashed+area`, `series`. |
## PanelOptions
### Properties
| Property | Type | Required | Description |
|-----------------------|---------|----------|------------------------------------------------------------------------------------------------------------------------------------|
| `barRadius` | number | No | TODO docs Default: `0`. |
| `barWidth` | number | No | Controls the width of bars. 1 = Max width, 0 = Min width. Default: `0.97`. |
| `colorByField` | string | No | TODO docs |
| `fullHighlight` | boolean | No | Enables mode which highlights the entire bar area and shows tooltip when cursor<br/>hovers over highlighted area Default: `false`. |
| `groupWidth` | number | No | Controls the width of groups. 1 = max with, 0 = min width. Default: `0.7`. |
| `orientation` | string | No | TODO docs Possible values are: `auto`, `vertical`, `horizontal`. |
| `showValue` | string | No | TODO docs Possible values are: `auto`, `never`, `always`. |
| `stacking` | string | No | TODO docs Possible values are: `none`, `normal`, `percent`. |
| `xField` | string | No | TODO docs |
| `xTickLabelMaxLength` | integer | No | TODO docs |
| `xTickLabelRotation` | integer | No | TODO docs Default: `0`. |
| `xTickLabelSpacing` | integer | No | TODO docs<br/>negative values indicate backwards skipping behavior Default: `0`. |

31
docs/sources/developers/kinds/composable/bargaugepanelcfg/schema-reference.md
Unescape View File

@ -0,0 +1,31 @@
---
keywords:
- grafana
- schema
title: BarGaugePanelCfg kind
---
> Both documentation generation and kinds schemas are in active development and subject to change without prior notice.
# BarGaugePanelCfg kind
### Maturity: experimental
### Version: 0.0
## Properties
| Property | Type | Required | Description |
|----------------|-------------------------|----------|-------------|
| `PanelOptions` | [object](#paneloptions) | **Yes** | |
## PanelOptions
### Properties
| Property | Type | Required | Description |
|----------------|---------|----------|-------------------------------------------------------------------------------------------------------------------------------------------|
| `displayMode` | string | No | Enum expressing the possible display modes<br/>for the bar gauge component of Grafana UI Possible values are: `basic`, `lcd`, `gradient`. |
| `minVizHeight` | integer | No | Default: `10`. |
| `minVizWidth` | integer | No | Default: `0`. |
| `showUnfilled` | boolean | No | Default: `true`. |

37
docs/sources/developers/kinds/composable/dashboardlistpanelcfg/schema-reference.md
Unescape View File

@ -0,0 +1,37 @@
---
keywords:
- grafana
- schema
title: DashboardListPanelCfg kind
---
> Both documentation generation and kinds schemas are in active development and subject to change without prior notice.
# DashboardListPanelCfg kind
### Maturity: experimental
### Version: 0.0
## Properties
| Property | Type | Required | Description |
|----------------|-------------------------|----------|------------------------------------------|
| `PanelLayout` | string | **Yes** | Possible values are: `list`, `previews`. |
| `PanelOptions` | [object](#paneloptions) | **Yes** | |
## PanelOptions
### Properties
| Property | Type | Required | Description |
|----------------------|----------|----------|------------------------------------------|
| `maxItems` | integer | **Yes** | Default: `10`. |
| `query` | string | **Yes** | Default: ``. |
| `showHeadings` | boolean | **Yes** | Default: `true`. |
| `showRecentlyViewed` | boolean | **Yes** | Default: `false`. |
| `showSearch` | boolean | **Yes** | Default: `false`. |
| `showStarred` | boolean | **Yes** | Default: `true`. |
| `tags` | string[] | **Yes** | |
| `folderId` | integer | No | |
| `layout` | string | No | Possible values are: `list`, `previews`. |

29
docs/sources/developers/kinds/composable/gaugepanelcfg/schema-reference.md
Unescape View File

@ -0,0 +1,29 @@
---
keywords:
- grafana
- schema
title: GaugePanelCfg kind
---
> Both documentation generation and kinds schemas are in active development and subject to change without prior notice.
# GaugePanelCfg kind
### Maturity: experimental
### Version: 0.0
## Properties
| Property | Type | Required | Description |
|----------------|-------------------------|----------|-------------|
| `PanelOptions` | [object](#paneloptions) | **Yes** | |
## PanelOptions
### Properties
| Property | Type | Required | Description |
|------------------------|---------|----------|-------------------|
| `showThresholdLabels` | boolean | No | Default: `false`. |
| `showThresholdMarkers` | boolean | No | Default: `true`. |

41
docs/sources/developers/kinds/composable/histogrampanelcfg/schema-reference.md
Unescape View File

@ -0,0 +1,41 @@
---
keywords:
- grafana
- schema
title: HistogramPanelCfg kind
---
> Both documentation generation and kinds schemas are in active development and subject to change without prior notice.
# HistogramPanelCfg kind
### Maturity: experimental
### Version: 0.0
## Properties
| Property | Type | Required | Description |
|--------------------|-----------------------------|----------|-------------|
| `PanelFieldConfig` | [object](#panelfieldconfig) | **Yes** | |
| `PanelOptions` | [object](#paneloptions) | **Yes** | |
## PanelFieldConfig
### Properties
| Property | Type | Required | Description |
|----------------|---------|----------|--------------------------------------------------------------------|
| `fillOpacity` | integer | No | Controls the fill opacity of the bars. Default: `80`. |
| `gradientMode` | string | No | TODO docs Possible values are: `none`, `opacity`, `hue`, `scheme`. |
| `lineWidth` | integer | No | Controls line width of the bars. Default: `1`. |
## PanelOptions
### Properties
| Property | Type | Required | Description |
|----------------|---------|----------|--------------------------------------------------|
| `bucketOffset` | integer | No | Offset buckets by this amount Default: `0`. |
| `bucketSize` | integer | No | Size of each bucket |
| `combine` | boolean | No | Combines multiple series into a single histogram |

29
docs/sources/developers/kinds/composable/newspanelcfg/schema-reference.md
Unescape View File

@ -0,0 +1,29 @@
---
keywords:
- grafana
- schema
title: NewsPanelCfg kind
---
> Both documentation generation and kinds schemas are in active development and subject to change without prior notice.
# NewsPanelCfg kind
### Maturity: experimental
### Version: 0.0
## Properties
| Property | Type | Required | Description |
|----------------|-------------------------|----------|-------------|
| `PanelOptions` | [object](#paneloptions) | **Yes** | |
## PanelOptions
### Properties
| Property | Type | Required | Description |
|-------------|---------|----------|--------------------------------------------|
| `feedUrl` | string | No | empty/missing will default to grafana blog |
| `showImage` | boolean | No | Default: `true`. |

73
docs/sources/developers/kinds/composable/piechartpanelcfg/schema-reference.md
Unescape View File

@ -0,0 +1,73 @@
---
keywords:
- grafana
- schema
title: PieChartPanelCfg kind
---
> Both documentation generation and kinds schemas are in active development and subject to change without prior notice.
# PieChartPanelCfg kind
### Maturity: experimental
### Version: 0.0
## Properties
| Property | Type | Required | Description |
|-------------------------|---------------------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `PanelFieldConfig` | [HideableFieldConfig](#hideablefieldconfig) | **Yes** | TODO docs |
| `PanelOptions` | [object](#paneloptions) | **Yes** | |
| `PieChartLabels` | string | **Yes** | Select labels to display on the pie chart.<br/> - Name - The series or field name.<br/> - Percent - The percentage of the whole.<br/> - Value - The raw numerical value. Possible values are: `name`, `value`, `percent`. |
| `PieChartLegendOptions` | [object](#piechartlegendoptions) | **Yes** | |
| `PieChartLegendValues` | string | **Yes** | Select values to display in the legend.<br/> - Percent: The percentage of the whole.<br/> - Value: The raw numerical value. Possible values are: `value`, `percent`. |
| `PieChartType` | string | **Yes** | Select the pie chart display style. Possible values are: `pie`, `donut`. |
## HideableFieldConfig
TODO docs
### Properties
| Property | Type | Required | Description |
|------------|---------------------------------------|----------|-------------|
| `hideFrom` | [HideSeriesConfig](#hideseriesconfig) | No | TODO docs |
### HideSeriesConfig
TODO docs
#### Properties
| Property | Type | Required | Description |
|-----------|---------|----------|-------------|
| `legend` | boolean | **Yes** | |
| `tooltip` | boolean | **Yes** | |
| `viz` | boolean | **Yes** | |
## PanelOptions
### Properties
| Property | Type | Required | Description |
|-----------------|-------------------------------------------------|----------|--------------------------------------------------------------------------|
| `displayLabels` | string[] | No | |
| `legend` | [PieChartLegendOptions](#piechartlegendoptions) | No | |
| `pieType` | string | No | Select the pie chart display style. Possible values are: `pie`, `donut`. |
### PieChartLegendOptions
#### Properties
| Property | Type | Required | Description |
|----------|----------|----------|-------------|
| `values` | string[] | No | |
## PieChartLegendOptions
### Properties
| Property | Type | Required | Description |
|----------|----------|----------|-------------|
| `values` | string[] | No | |

31
docs/sources/developers/kinds/composable/statpanelcfg/schema-reference.md
Unescape View File

@ -0,0 +1,31 @@
---
keywords:
- grafana
- schema
title: StatPanelCfg kind
---
> Both documentation generation and kinds schemas are in active development and subject to change without prior notice.
# StatPanelCfg kind
### Maturity: experimental
### Version: 0.0
## Properties
| Property | Type | Required | Description |
|----------------|-------------------------|----------|-------------|
| `PanelOptions` | [object](#paneloptions) | **Yes** | |
## PanelOptions
### Properties
| Property | Type | Required | Description |
|---------------|--------|----------|-----------------------------------------------------------------------------------|
| `colorMode` | string | No | TODO docs Possible values are: `value`, `background`, `none`. |
| `graphMode` | string | No | TODO docs Possible values are: `none`, `line`, `area`. |
| `justifyMode` | string | No | TODO docs Possible values are: `auto`, `center`. |
| `textMode` | string | No | TODO docs Possible values are: `auto`, `value`, `value_and_name`, `name`, `none`. |

53
docs/sources/developers/kinds/composable/textpanelcfg/schema-reference.md
Unescape View File

@ -0,0 +1,53 @@
---
keywords:
- grafana
- schema
title: TextPanelCfg kind
---
> Both documentation generation and kinds schemas are in active development and subject to change without prior notice.
# TextPanelCfg kind
### Maturity: experimental
### Version: 0.0
## Properties
| Property | Type | Required | Description |
|----------------|-------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------|
| `CodeLanguage` | string | **Yes** | Possible values are: `plaintext`, `yaml`, `xml`, `typescript`, `sql`, `go`, `markdown`, `html`, `json`. Default: `plaintext`. |
| `CodeOptions` | [object](#codeoptions) | **Yes** | |
| `PanelOptions` | [object](#paneloptions) | **Yes** | |
| `TextMode` | string | **Yes** | Possible values are: `html`, `markdown`, `code`. |
## CodeOptions
### Properties
| Property | Type | Required | Description |
|-------------------|---------|----------|-------------------------------------------------------------------------------------------------------------------------------|
| `language` | string | **Yes** | Possible values are: `plaintext`, `yaml`, `xml`, `typescript`, `sql`, `go`, `markdown`, `html`, `json`. Default: `plaintext`. |
| `showLineNumbers` | boolean | **Yes** | Default: `false`. |
| `showMiniMap` | boolean | **Yes** | Default: `false`. |
## PanelOptions
### Properties
| Property | Type | Required | Description |
|-----------|-----------------------------|----------|------------------------------------------------------------------------------------------------------------|
| `content` | string | **Yes** | Default: `# Title<br/><br/>For markdown syntax help: [commonmark.org/help](https://commonmark.org/help/)`. |
| `mode` | string | **Yes** | Possible values are: `html`, `markdown`, `code`. |
| `code` | [CodeOptions](#codeoptions) | No | |
### CodeOptions
#### Properties
| Property | Type | Required | Description |
|-------------------|---------|----------|-------------------------------------------------------------------------------------------------------------------------------|
| `language` | string | **Yes** | Possible values are: `plaintext`, `yaml`, `xml`, `typescript`, `sql`, `go`, `markdown`, `html`, `json`. Default: `plaintext`. |
| `showLineNumbers` | boolean | **Yes** | Default: `false`. |
| `showMiniMap` | boolean | **Yes** | Default: `false`. |

1
docs/sources/developers/kinds/core/dashboard/schema-reference.md
Unescape View File

@ -4,6 +4,7 @@ keywords:
- schema
title: Dashboard kind
---
> Both documentation generation and kinds schemas are in active development and subject to change without prior notice.
# Dashboard kind

1
docs/sources/developers/kinds/core/playlist/schema-reference.md
Unescape View File

@ -4,6 +4,7 @@ keywords:
- schema
title: Playlist kind
---
> Both documentation generation and kinds schemas are in active development and subject to change without prior notice.
# Playlist kind

1
docs/sources/developers/kinds/core/team/schema-reference.md
Unescape View File

@ -4,6 +4,7 @@ keywords:
- schema
title: Team kind
---
> Both documentation generation and kinds schemas are in active development and subject to change without prior notice.
# Team kind

10
pkg/codegen/jenny_docs.go
Unescape View File

@ -46,6 +46,9 @@ func (j docsJenny) Generate(decl *DeclForGen) (*codejen.File, error) {
// We don't need entire json obj, only the value of components.schemas path
var obj struct {
Info struct {
Title string
}
Components struct {
Schemas json.RawMessage
}
@ -59,7 +62,6 @@ func (j docsJenny) Generate(decl *DeclForGen) (*codejen.File, error) {
kindJsonStr := strings.Replace(string(obj.Components.Schemas), "#/components/schemas/", "#/", -1)
kindProps := decl.Properties.Common()
kindName := strings.ToLower(kindProps.Name)
data := templateData{
KindName: kindProps.Name,
KindVersion: decl.Lineage().Latest().Version().String(),
@ -72,12 +74,12 @@ func (j docsJenny) Generate(decl *DeclForGen) (*codejen.File, error) {
return nil, err
}
doc, err := jsonToMarkdown([]byte(kindJsonStr), string(tmpl), kindName)
doc, err := jsonToMarkdown([]byte(kindJsonStr), string(tmpl), obj.Info.Title)
if err != nil {
return nil, fmt.Errorf("failed to build markdown for kind %s: %v", kindName, err)
return nil, fmt.Errorf("failed to build markdown for kind %s: %v", kindProps.Name, err)
}
return codejen.NewFile(filepath.Join(j.docsPath, kindName, "schema-reference.md"), doc, j), nil
return codejen.NewFile(filepath.Join(j.docsPath, strings.ToLower(kindProps.Name), "schema-reference.md"), doc, j), nil
}
// makeTemplate pre-populates the template with the kind metadata

1
pkg/codegen/tmpl/docs.tmpl
Unescape View File

@ -4,6 +4,7 @@ keywords:
- schema
title: {{ .KindName }} kind
---
> Both documentation generation and kinds schemas are in active development and subject to change without prior notice.
# {{ .KindName }} kind

28
pkg/plugins/codegen/jenny_plugindocs.go
Unescape View File

@ -0,0 +1,28 @@
package codegen
import (
"github.com/grafana/codejen"
"github.com/grafana/grafana/pkg/plugins/pfs"
)
func PluginDocsJenny(inner codejen.OneToOne[*pfs.PluginDecl]) codejen.OneToOne[*pfs.PluginDecl] {
return &docsJenny{
inner: inner,
}
}
type docsJenny struct {
inner codejen.OneToOne[*pfs.PluginDecl]
}
func (j *docsJenny) JennyName() string {
return "PluginDocsJenny"
}
func (j *docsJenny) Generate(decl *pfs.PluginDecl) (*codejen.File, error) {
if !decl.HasSchema() {
return nil, nil
}
return j.inner.Generate(decl)
}

1
pkg/plugins/pfs/decl.go
Unescape View File

@ -13,6 +13,7 @@ type PluginDecl struct {
Imports []*ast.ImportSpec
PluginPath string
PluginMeta plugindef.PluginDef
KindDecl kindsys.Decl[kindsys.ComposableProperties]
}
func EmptyPluginDecl(path string, meta plugindef.PluginDef) *PluginDecl {

1
pkg/plugins/pfs/decl_parser.go
Unescape View File

@ -61,6 +61,7 @@ func (psr *declParser) Parse(root fs.FS) ([]*PluginDecl, error) {
Imports: pp.CUEImports,
PluginMeta: pp.Properties,
PluginPath: path,
KindDecl: kind.Decl(),
})
}
}

13
public/app/plugins/gen.go
Unescape View File

@ -56,6 +56,9 @@ func main() {
codegen.PluginTreeListJenny(),
codegen.PluginGoTypesJenny("pkg/tsdb", adaptToPipeline(corecodegen.GoTypesJenny{ExpandReferences: true})),
codegen.PluginTSTypesJenny("public/app/plugins", adaptToPipeline(corecodegen.TSTypesJenny{})),
codegen.PluginDocsJenny(toDeclForGen(corecodegen.DocsJenny(
filepath.Join("docs", "sources", "developers", "kinds", "composable"),
))),
)
pluginKindGen.AddPostprocessors(corecodegen.SlashHeaderMapper("public/app/plugins/gen.go"))
@ -89,3 +92,13 @@ func adaptToPipeline(j codejen.OneToOne[corecodegen.SchemaForGen]) codejen.OneTo
}
})
}
func toDeclForGen(j codejen.OneToOne[*corecodegen.DeclForGen]) codejen.OneToOne[*pfs.PluginDecl] {
return codejen.AdaptOneToOne(j, func(pd *pfs.PluginDecl) *corecodegen.DeclForGen {
kd, err := corecodegen.ForGen(pd.Lineage.Runtime(), pd.KindDecl.Some())
if err != nil {
panic("should be unreachable")
}
return kd
})
}

Write Preview
Loading…
Cancel
Save