From c84de88229715adff553dddb2e254f37538dd91f Mon Sep 17 00:00:00 2001 From: Ludovic Fernandez Date: Thu, 20 Jan 2022 01:20:51 +0100 Subject: [PATCH] docs: split configuration page into multiple sections (#2484) --- .golangci.yml | 2 +- docs/package-lock.json | 1 + docs/src/docs/usage/configuration.mdx | 32 ++-- scripts/expand_website_templates/main.go | 178 ++++++++++++++---- scripts/expand_website_templates/main_test.go | 20 ++ 5 files changed, 180 insertions(+), 53 deletions(-) create mode 100644 scripts/expand_website_templates/main_test.go diff --git a/.golangci.yml b/.golangci.yml index 1d91641ab188..3cc116d03bf8 100644 --- a/.golangci.yml +++ b/.golangci.yml @@ -16,7 +16,7 @@ linters-settings: local-prefixes: github.com/golangci/golangci-lint goconst: min-len: 2 - min-occurrences: 2 + min-occurrences: 3 gocritic: enabled-tags: - diagnostic diff --git a/docs/package-lock.json b/docs/package-lock.json index bae63f019e06..351f9db71057 100644 --- a/docs/package-lock.json +++ b/docs/package-lock.json @@ -24195,6 +24195,7 @@ "version": "0.27.1", "resolved": "https://registry.npmjs.org/sharp/-/sharp-0.27.1.tgz", "integrity": "sha512-IQNXWdspb4nZcJemXa6cfgz+JvKONsuqP8Mwi1Oti23Uo7+J+UF2jihJDf6I1BQbrmhcZ0lagH/1WYG+ReAzyQ==", + "hasInstallScript": true, "dependencies": { "array-flatten": "^3.0.0", "color": "^3.1.3", diff --git a/docs/src/docs/usage/configuration.mdx b/docs/src/docs/usage/configuration.mdx index ae0d87955bda..1a1102be34ac 100644 --- a/docs/src/docs/usage/configuration.mdx +++ b/docs/src/docs/usage/configuration.mdx @@ -12,19 +12,6 @@ To see a list of enabled by your configuration linters: golangci-lint linters ``` -## Command-Line Options - -```sh -golangci-lint run -h -{.RunHelpText} -``` - -When the `--cpu-profile-path` or `--mem-profile-path` arguments are specified, `golangci-lint` writes runtime profiling data -in the format expected by the [pprof](https://github.com/google/pprof) visualization tool. - -When the `--trace-path` argument is specified, `golangci-lint` writes runtime tracing data in the format expected by -the `go tool trace` command and visualization tool. - ## Config File GolangCI-Lint looks for config files in the following paths from the current working directory: @@ -41,13 +28,24 @@ To see which config file is being used and where it was sourced from run golangc Config options inside the file are identical to command-line options. You can configure specific linters' options only within the config file (not the command-line). -There is a [`.golangci.example.yml`](https://github.com/golangci/golangci-lint/blob/master/.golangci.example.yml) example -config file with all supported options, their description and default value: +There is a [`.golangci.example.yml`](https://github.com/golangci/golangci-lint/blob/master/.golangci.example.yml) file with all supported options, their description, and default values. +This file is a neither a working example nor recommended configuration, it's just a reference to display all the configuration options. -```yaml -{ .GolangciYamlExample } +{ .ConfigurationExample } + +## Command-Line Options + +```sh +golangci-lint run -h +{.RunHelpText} ``` +When the `--cpu-profile-path` or `--mem-profile-path` arguments are specified, `golangci-lint` writes runtime profiling data +in the format expected by the [pprof](https://github.com/google/pprof) visualization tool. + +When the `--trace-path` argument is specified, `golangci-lint` writes runtime tracing data in the format expected by +the `go tool trace` command and visualization tool. + ## Cache GolangCI-Lint stores its cache in the [default user cache directory](https://golang.org/pkg/os/#UserCacheDir). diff --git a/scripts/expand_website_templates/main.go b/scripts/expand_website_templates/main.go index 9d045cf93bad..d82e94abefe7 100644 --- a/scripts/expand_website_templates/main.go +++ b/scripts/expand_website_templates/main.go @@ -165,7 +165,7 @@ func buildTemplateContext() (map[string]string, error) { return nil, fmt.Errorf("can't read .golangci.example.yml: %s", err) } - lintersCfg, err := getLintersConfiguration(golangciYamlExample) + snippets, err := extractExampleSnippets(golangciYamlExample) if err != nil { return nil, fmt.Errorf("can't read .golangci.example.yml: %s", err) } @@ -202,8 +202,8 @@ func buildTemplateContext() (map[string]string, error) { } return map[string]string{ - "LintersExample": lintersCfg, - "GolangciYamlExample": strings.TrimSpace(string(golangciYamlExample)), + "LintersExample": snippets.LintersSettings, + "ConfigurationExample": snippets.ConfigurationFile, "LintersCommandOutputEnabledOnly": string(lintersOutParts[0]), "LintersCommandOutputDisabledOnly": string(lintersOutParts[1]), "EnabledByDefaultLinters": getLintersListMarkdown(true), @@ -317,58 +317,166 @@ func getThanksList() string { return strings.Join(lines, "\n") } -func getLintersConfiguration(example []byte) (string, error) { - builder := &strings.Builder{} +type SettingSnippets struct { + ConfigurationFile string + LintersSettings string +} +func extractExampleSnippets(example []byte) (*SettingSnippets, error) { var data yaml.Node err := yaml.Unmarshal(example, &data) if err != nil { - return "", err + return nil, err } root := data.Content[0] + globalNode := &yaml.Node{ + Kind: root.Kind, + Style: root.Style, + Tag: root.Tag, + Value: root.Value, + Anchor: root.Anchor, + Alias: root.Alias, + HeadComment: root.HeadComment, + LineComment: root.LineComment, + FootComment: root.FootComment, + Line: root.Line, + Column: root.Column, + } + + snippets := SettingSnippets{} + + builder := strings.Builder{} + for j, node := range root.Content { - if node.Value != "linters-settings" { + switch node.Value { + case "run", "output", "linters", "linters-settings", "issues", "severity": + default: continue } - nodes := root.Content[j+1] - - for i := 0; i < len(nodes.Content); i += 2 { - r := &yaml.Node{ - Kind: nodes.Kind, - Style: nodes.Style, - Tag: nodes.Tag, - Value: node.Value, - Content: []*yaml.Node{ - { - Kind: root.Content[j].Kind, - Value: root.Content[j].Value, - }, - { - Kind: nodes.Kind, - Content: []*yaml.Node{nodes.Content[i], nodes.Content[i+1]}, - }, + nextNode := root.Content[j+1] + + newNode := &yaml.Node{ + Kind: nextNode.Kind, + Content: []*yaml.Node{ + { + HeadComment: fmt.Sprintf("See the dedicated %q documentation section.", node.Value), + Kind: node.Kind, + Style: node.Style, + Tag: node.Tag, + Value: "option", }, - } - - _, _ = fmt.Fprintf(builder, "### %s\n\n", nodes.Content[i].Value) - _, _ = fmt.Fprintln(builder, "```yaml") + { + Kind: node.Kind, + Style: node.Style, + Tag: node.Tag, + Value: "value", + }, + }, + } - const ident = 2 - encoder := yaml.NewEncoder(builder) - encoder.SetIndent(ident) + globalNode.Content = append(globalNode.Content, node, newNode) - err = encoder.Encode(r) + if node.Value == "linters-settings" { + snippets.LintersSettings, err = getLintersSettingSnippets(node, nextNode) if err != nil { - return "", err + return nil, err } - _, _ = fmt.Fprintln(builder, "```") - _, _ = fmt.Fprintln(builder) + _, _ = builder.WriteString( + fmt.Sprintf( + "### `%s` configuration\n\nSee the dedicated [linters-settings](/usage/linters) documentation section.\n\n", + node.Value, + ), + ) + continue + } + + nodeSection := &yaml.Node{ + Kind: root.Kind, + Style: root.Style, + Tag: root.Tag, + Value: root.Value, + Content: []*yaml.Node{node, nextNode}, + } + + snippet, errSnip := marshallSnippet(nodeSection) + if errSnip != nil { + return nil, errSnip + } + + _, _ = builder.WriteString(fmt.Sprintf("### `%s` configuration\n\n%s", node.Value, snippet)) + } + + overview, err := marshallSnippet(globalNode) + if err != nil { + return nil, err + } + + snippets.ConfigurationFile = overview + builder.String() + + return &snippets, nil +} + +func getLintersSettingSnippets(node, nextNode *yaml.Node) (string, error) { + builder := &strings.Builder{} + + for i := 0; i < len(nextNode.Content); i += 2 { + r := &yaml.Node{ + Kind: nextNode.Kind, + Style: nextNode.Style, + Tag: nextNode.Tag, + Value: node.Value, + Content: []*yaml.Node{ + { + Kind: node.Kind, + Value: node.Value, + }, + { + Kind: nextNode.Kind, + Content: []*yaml.Node{nextNode.Content[i], nextNode.Content[i+1]}, + }, + }, } + + _, _ = fmt.Fprintf(builder, "### %s\n\n", nextNode.Content[i].Value) + _, _ = fmt.Fprintln(builder, "```yaml") + + encoder := yaml.NewEncoder(builder) + encoder.SetIndent(2) + + err := encoder.Encode(r) + if err != nil { + return "", err + } + + _, _ = fmt.Fprintln(builder, "```") + _, _ = fmt.Fprintln(builder) } return builder.String(), nil } + +func marshallSnippet(node *yaml.Node) (string, error) { + builder := &strings.Builder{} + + if node.Value != "" { + _, _ = fmt.Fprintf(builder, "### %s\n\n", node.Value) + } + _, _ = fmt.Fprintln(builder, "```yaml") + + encoder := yaml.NewEncoder(builder) + encoder.SetIndent(2) + + err := encoder.Encode(node) + if err != nil { + return "", err + } + + _, _ = fmt.Fprintln(builder, "```") + _, _ = fmt.Fprintln(builder) + + return builder.String(), nil +} diff --git a/scripts/expand_website_templates/main_test.go b/scripts/expand_website_templates/main_test.go new file mode 100644 index 000000000000..24afffb8b59b --- /dev/null +++ b/scripts/expand_website_templates/main_test.go @@ -0,0 +1,20 @@ +package main + +import ( + "os" + "testing" + + "github.com/stretchr/testify/require" +) + +func Test_extractExampleSnippets(t *testing.T) { + t.Skip("only for debugging purpose") + + example, err := os.ReadFile("../../../golangci-lint/.golangci.example.yml") + require.NoError(t, err) + + m, err := extractExampleSnippets(example) + require.NoError(t, err) + + t.Log(m) +}