Skip to content

Commit a70ccf0

Browse files
LukasGenteleLukasGentele
committed
docs: cli reference generation
1 parent a40857f commit a70ccf0

437 files changed

Lines changed: 3516 additions & 1468 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/hack/config/partials/main.go‎

Lines changed: 32 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ import (
1313
)
1414

1515
const configPartialBasePath = "docs/pages/configuration/_partials/"
16+
const nameFieldName = "name"
1617

1718
func main() {
1819
r := new(jsonschema.Reflector)
@@ -29,55 +30,61 @@ func main() {
2930

3031
schema := r.Reflect(&latest.Config{})
3132

32-
createSections("", schema, schema.Definitions, 1)
33+
createSections("", schema, schema.Definitions, 1, false)
3334
}
3435

35-
func createSections(prefix string, schema *jsonschema.Schema, definitions jsonschema.Definitions, depth int) string {
36+
func createSections(prefix string, schema *jsonschema.Schema, definitions jsonschema.Definitions, depth int, parentIsNameObjectMap bool) string {
3637
partialImports := &[]string{}
3738
content := ""
39+
headlinePrefix := strings.Repeat("#", depth+1) + " "
3840

3941
for _, fieldName := range schema.Properties.Keys() {
42+
if parentIsNameObjectMap && fieldName == nameFieldName {
43+
continue
44+
}
4045

4146
field, ok := schema.Properties.Get(fieldName)
4247
if ok {
4348
if fieldSchema, ok := field.(*jsonschema.Schema); ok {
4449
fieldContent := ""
4550
fieldFile := fmt.Sprintf(configPartialBasePath+"%s/%s%s.mdx", latest.Version, prefix, fieldName)
51+
fieldType := "object"
52+
isNameObjectMap := false
53+
54+
var nestedSchema *jsonschema.Schema
4655

4756
ref := ""
4857
if fieldSchema.Type == "array" {
4958
ref = fieldSchema.Items.Ref
59+
fieldType = "object[]"
5060
} else if patternPropertySchema, ok := fieldSchema.PatternProperties[".*"]; ok {
5161
ref = patternPropertySchema.Ref
62+
isNameObjectMap = true
5263
} else if fieldSchema.Ref != "" {
5364
ref = fieldSchema.Ref
5465
}
5566

5667
if ref != "" {
5768
refSplit := strings.Split(ref, "/")
58-
nestedSchema, ok := definitions[refSplit[len(refSplit)-1]]
69+
nestedSchema, ok = definitions[refSplit[len(refSplit)-1]]
5970

6071
if ok {
6172
newPrefix := prefix + fieldName + "/"
62-
createSections(newPrefix, nestedSchema, definitions, depth+1)
73+
createSections(newPrefix, nestedSchema, definitions, depth+1, isNameObjectMap)
6374
}
6475
} else {
65-
required := ""
66-
if contains(schema.Required, fieldName) {
67-
required = util.TemplateConfigFieldRequired
76+
required := contains(schema.Required, fieldName)
77+
fieldType = fieldSchema.Type
78+
if fieldType == "array" {
79+
fieldType = fieldSchema.Items.Type + "[]"
6880
}
6981

70-
fieldTypeRaw := fieldSchema.Type
71-
if fieldTypeRaw == "array" {
72-
fieldTypeRaw = fieldSchema.Items.Type + "[]"
73-
}
74-
fieldType := fmt.Sprintf(util.TemplateConfigFieldType, fieldTypeRaw)
75-
fieldDefault := ""
76-
if fieldSchema.Default != nil {
77-
fieldDefault = fmt.Sprintf(util.TemplateConfigFieldType, fieldSchema.Default)
82+
fieldDefault, ok := fieldSchema.Default.(string)
83+
if !ok {
84+
fieldDefault = ""
7885
}
7986

80-
fieldContent = fmt.Sprintf(util.TemplateConfigField, fieldName, required, fieldType, fieldDefault, fieldSchema.Description)
87+
fieldContent = fmt.Sprintf(util.TemplateConfigField, false, " open", headlinePrefix, fieldName, required, fieldType, fieldDefault, fieldSchema.Description, "")
8188

8289
err := os.MkdirAll(filepath.Dir(fieldFile), os.ModePerm)
8390
if err != nil {
@@ -93,8 +100,15 @@ func createSections(prefix string, schema *jsonschema.Schema, definitions jsonsc
93100
*partialImports = append(*partialImports, fieldFile)
94101
fieldPartial := fmt.Sprintf(util.TemplatePartialUse, util.GetPartialImportName(fieldFile))
95102
if ref != "" {
96-
fieldSummary := fmt.Sprintf("<h%d><code>%s</code></h%d>", depth+1, fieldName, depth+1)
97-
fieldPartial = fmt.Sprintf("<details><summary>%s</summary>\n%s\n</details>", fieldSummary, fieldPartial)
103+
if isNameObjectMap && nestedSchema != nil {
104+
nameField, ok := nestedSchema.Properties.Get(nameFieldName)
105+
if ok {
106+
if nameFieldSchema, ok := nameField.(*jsonschema.Schema); ok {
107+
fieldPartial = fmt.Sprintf(util.TemplateConfigField, true, "open", headlinePrefix, "<"+nameFieldName+">", false, "object", "", nameFieldSchema.Description, fieldPartial)
108+
}
109+
}
110+
}
111+
fieldPartial = fmt.Sprintf(util.TemplateConfigField, true, "", headlinePrefix, fieldName, false, fieldType, "", fieldSchema.Description, fieldPartial)
98112
}
99113

100114
content = content + "\n\n" + fieldPartial

‎docs/hack/util/templates.go‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -35,14 +35,13 @@ const TemplateFlag = AutoGenTagBegin + `
3535
### ` + "`--%s%s`" + `
3636
%s
3737
` + AutoGenTagEnd + "\n\n"
38-
const TemplateConfigFieldRequired = `<span class="config-field-required">required</span>`
39-
const TemplateConfigFieldDefault = `<span class="config-field-default">Default: %s</span>`
40-
const TemplateConfigFieldType = `<span class="config-field-type">%s</span>`
4138
const TemplateConfigField = `
42-
<details>
39+
<details className="config-field" data-expandable="%t"%s>
4340
<summary>
4441
45-
` + "`%s`" + ` %s %s %s
42+
%s` + "`%s`" + ` <span class="config-field-required" data-required="%t">required</span> <span class="config-field-type">%s</span> <span class="config-field-default">%s</span>
43+
44+
%s
4645
4746
</summary>
4847

‎docs/pages/configuration/_partials/v2beta1/commands.mdx‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
11

2-
import PartialName from "./commands/name.mdx"
32
import PartialCommand from "./commands/command.mdx"
43
import PartialAfter from "./commands/after.mdx"
54
import PartialDisableReplace from "./commands/disableReplace.mdx"
@@ -8,9 +7,6 @@ import PartialArgs from "./commands/args.mdx"
87
import PartialAppendArgs from "./commands/appendArgs.mdx"
98
import PartialDescription from "./commands/description.mdx"
109

11-
<PartialName />
12-
13-
1410
<PartialCommand />
1511

1612

‎docs/pages/configuration/_partials/v2beta1/commands/after.mdx‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,16 @@
11

2-
<details>
2+
<details className="config-field" data-expandable="false" open>
33
<summary>
44

5-
`after` <span class="config-field-type">string</span>
6-
7-
</summary>
5+
### `after` <span class="config-field-required" data-required="false">required</span> <span class="config-field-type">string</span> <span class="config-field-default"></span>
86

97
After is executed after the command was run. It is executed also when
108
the command was interrupted which will set the env variable COMMAND_INTERRUPT
119
to true as well as when the command errored which will set the error string to
1210
COMMAND_ERROR.
1311

12+
</summary>
13+
14+
15+
1416
</details>

‎docs/pages/configuration/_partials/v2beta1/commands/appendArgs.mdx‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,14 @@
11

2-
<details>
2+
<details className="config-field" data-expandable="false" open>
33
<summary>
44

5-
`appendArgs` <span class="config-field-type">boolean</span>
6-
7-
</summary>
5+
### `appendArgs` <span class="config-field-required" data-required="false">required</span> <span class="config-field-type">boolean</span> <span class="config-field-default"></span>
86

97
AppendArgs will append arguments passed to the DevSpace command automatically to
108
the specified command.
119

10+
</summary>
11+
12+
13+
1214
</details>

‎docs/pages/configuration/_partials/v2beta1/commands/args.mdx‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,14 @@
11

2-
<details>
2+
<details className="config-field" data-expandable="false" open>
33
<summary>
44

5-
`args` <span class="config-field-type">string[]</span>
6-
7-
</summary>
5+
### `args` <span class="config-field-required" data-required="false">required</span> <span class="config-field-type">string[]</span> <span class="config-field-default"></span>
86

97
Args are optional and if defined, command is not executed within a shell
108
and rather directly.
119

10+
</summary>
11+
12+
13+
1214
</details>

‎docs/pages/configuration/_partials/v2beta1/commands/command.mdx‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
11

2-
<details>
2+
<details className="config-field" data-expandable="false" open>
33
<summary>
44

5-
`command` <span class="config-field-required">required</span> <span class="config-field-type">string</span>
5+
### `command` <span class="config-field-required" data-required="true">required</span> <span class="config-field-type">string</span> <span class="config-field-default"></span>
6+
7+
Command is the command that should be executed. For example: 'echo 123'
68

79
</summary>
810

9-
Command is the command that should be executed. For example: 'echo 123'
11+
1012

1113
</details>

‎docs/pages/configuration/_partials/v2beta1/commands/description.mdx‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
11

2-
<details>
2+
<details className="config-field" data-expandable="false" open>
33
<summary>
44

5-
`description` <span class="config-field-type">string</span>
5+
### `description` <span class="config-field-required" data-required="false">required</span> <span class="config-field-type">string</span> <span class="config-field-default"></span>
6+
7+
Description describes what the command is doing and can be seen in `devspace list commands`
68

79
</summary>
810

9-
Description describes what the command is doing and can be seen in `devspace list commands`
11+
1012

1113
</details>

‎docs/pages/configuration/_partials/v2beta1/commands/disableReplace.mdx‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,14 @@
11

2-
<details>
2+
<details className="config-field" data-expandable="false" open>
33
<summary>
44

5-
`disableReplace` <span class="config-field-type">boolean</span>
6-
7-
</summary>
5+
### `disableReplace` <span class="config-field-required" data-required="false">required</span> <span class="config-field-type">boolean</span> <span class="config-field-default"></span>
86

97
DisableReplace signals DevSpace to not replace the default command. E.g.
108
dev does not replace devspace dev.
119

10+
</summary>
11+
12+
13+
1214
</details>

‎docs/pages/configuration/_partials/v2beta1/commands/internal.mdx‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
11

2-
<details>
2+
<details className="config-field" data-expandable="false" open>
33
<summary>
44

5-
`internal` <span class="config-field-type">boolean</span>
5+
### `internal` <span class="config-field-required" data-required="false">required</span> <span class="config-field-type">boolean</span> <span class="config-field-default"></span>
6+
7+
Internal commands are not show in list and are usable through run_command
68

79
</summary>
810

9-
Internal commands are not show in list and are usable through run_command
11+
1012

1113
</details>

0 commit comments

Comments
 (0)