docs: improve linters page (#1995)

* TOC level 3 * drop `.golangci.yaml` from the Configuration page * generate a dedicated configuration section for each linters. * fix changelog heading
2021-05-17 23:56:46 +02:00 · 2021-05-17 23:56:46 +02:00 · fcef82475c
commit fcef82475c
parent 874304dd90
11 changed files with 86 additions and 25 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -1,7 +1,7 @@
 Follow the news and releases on our [twitter](https://twitter.com/golangci) and our [blog](https://medium.com/golangci).
 There is the most valuable changes log:

-## May 2021
+### May 2021

 1. new linters:
   * `tagliatelle`: https://github.com/ldez/tagliatelle
@ -25,7 +25,7 @@ There is the most valuable changes log:
   * set the minimum Go version to go1.15
   * non-zero exit code when a linter produces a panic

-## April 2021
+### April 2021

 1. new linters:
   * `tagliatelle`: https://github.com/ldez/tagliatelle
@ -46,7 +46,7 @@ There is the most valuable changes log:
 4. Misc:
   * fix: comma in exclude pattern leads to unexpected results

-## March 2021
+### March 2021

 1. new linters:
   * `gomoddirectives`: https://github.com/ldez/gomoddirectives
@ -76,7 +76,7 @@ There is the most valuable changes log:
   * fix linters load mode
   * Restore fast linters meaning

-## February 2021
+### February 2021

 1. new linters:
   * `durationcheck`: https://github.com/charithe/durationcheck
@ -124,7 +124,7 @@ There is the most valuable changes log:
   * update deprecated hyperlink for Sublime Text plugin
   * add docs on using homebrew tap

-## January 2021
+### January 2021

 1. new linters:
   * `predeclared`: https://github.com/nishanths/predeclared
@ -144,7 +144,7 @@ There is the most valuable changes log:
 4. documentation:
   * bump documentation dependencies

-## December 2020
+### December 2020

 1. new linters:
   * `forbidigo`: https://github.com/ashanbrown/forbidigo
--- a/docs/src/@rocketseat/gatsby-theme-docs/src/components/Docs/TOC/index.js
+++ b/docs/src/@rocketseat/gatsby-theme-docs/src/components/Docs/TOC/index.js
@ -13,9 +13,14 @@ export default function TableOfContents({ headings }) {
        <nav>
          <ul>
            {headings
-              .filter(heading => heading.depth === 2)
+              .filter((heading) => heading.depth === 2 || heading.depth === 3)
              .map(heading => (
-                <li key={heading.value}>
+                <li
+                  key={heading.value}
+                  style={{
+                    marginLeft: heading.depth === 3 ? `8px` : null,
+                  }}
+                >
                  <a href={`#${slug(heading.value)}`}>{heading.value}</a>
                </li>
              ))}
--- a/docs/src/docs/usage/configuration.mdx
+++ b/docs/src/docs/usage/configuration.mdx
@ -48,13 +48,6 @@ config file with all supported options, their description and default value:
 { .GolangciYamlExample }
 ```

-It's a [.golangci.yml](https://github.com/golangci/golangci-lint/blob/master/.golangci.yml) config file of this repo: we enable more linters
-than the default and have more strict settings:
-
-```yaml
-{ .GolangciYaml }
-```
-
 ## Cache

 GolangCI-Lint stores its cache in the [default user cache directory](https://golang.org/pkg/os/#UserCacheDir).
--- a/docs/src/docs/usage/linters.mdx
+++ b/docs/src/docs/usage/linters.mdx
@ -15,3 +15,7 @@ golangci-lint help linters
 ## Disabled By Default Linters (`-E/--enable`)

 {.DisabledByDefaultLinters}
+
+## Linters Configuration
+
+{ .LintersExample }
--- a/go.mod
+++ b/go.mod
@ -83,7 +83,7 @@ require (
 	github.com/valyala/quicktemplate v1.6.3
 	github.com/yeya24/promlinter v0.1.0
 	golang.org/x/tools v0.1.2-0.20210512205948-8287d5da45e4
-	gopkg.in/yaml.v2 v2.4.0
+	gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b
 	honnef.co/go/tools v0.1.4
 	mvdan.cc/gofumpt v0.1.1
 	mvdan.cc/interfacer v0.0.0-20180901003855-c20040233aed
--- a/go.sum
+++ b/go.sum
@ -1041,8 +1041,9 @@ gopkg.in/yaml.v2 v2.2.8/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v2 v2.3.0/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
 gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
-gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c h1:dUUwHk2QECo/6vqA44rthZ8ie2QXMNeKRTHCNY2nXvo=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b h1:h8qDotaEPuJATrMmW04NCwg7v22aHH28wwpauUhK9Oo=
+gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 honnef.co/go/tools v0.0.0-20190102054323-c2f93a96b099/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
 honnef.co/go/tools v0.0.0-20190106161140-3f1c8253044a/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
 honnef.co/go/tools v0.0.0-20190418001031-e561f6794a2a/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
--- a/scripts/expand_website_templates/main.go
+++ b/scripts/expand_website_templates/main.go
@ -16,6 +16,8 @@ import (
 	"sort"
 	"strings"

+	"gopkg.in/yaml.v3"
+
 	"github.com/golangci/golangci-lint/internal/renameio"
 	"github.com/golangci/golangci-lint/pkg/lint/linter"
 	"github.com/golangci/golangci-lint/pkg/lint/lintersdb"
@ -158,12 +160,12 @@ func getLatestVersion() (string, error) {
 }

 func buildTemplateContext() (map[string]string, error) {
-	golangciYaml, err := ioutil.ReadFile(".golangci.yml")
+	golangciYamlExample, err := ioutil.ReadFile(".golangci.example.yml")
 	if err != nil {
-		return nil, fmt.Errorf("can't read .golangci.yml: %s", err)
+		return nil, fmt.Errorf("can't read .golangci.example.yml: %s", err)
 	}

-	golangciYamlExample, err := ioutil.ReadFile(".golangci.example.yml")
+	lintersCfg, err := getLintersConfiguration(golangciYamlExample)
 	if err != nil {
 		return nil, fmt.Errorf("can't read .golangci.example.yml: %s", err)
 	}
@ -200,7 +202,7 @@ func buildTemplateContext() (map[string]string, error) {
 	}

 	return map[string]string{
-		"GolangciYaml":                     strings.TrimSpace(string(golangciYaml)),
+		"LintersExample":                   lintersCfg,
 		"GolangciYamlExample":              strings.TrimSpace(string(golangciYamlExample)),
 		"LintersCommandOutputEnabledOnly":  string(lintersOutParts[0]),
 		"LintersCommandOutputDisabledOnly": string(lintersOutParts[1]),
@ -314,3 +316,59 @@ func getThanksList() string {

 	return strings.Join(lines, "\n")
 }
+
+func getLintersConfiguration(example []byte) (string, error) {
+	builder := &strings.Builder{}
+
+	var data yaml.Node
+	err := yaml.Unmarshal(example, &data)
+	if err != nil {
+		return "", err
+	}
+
+	root := data.Content[0]
+
+	for j, node := range root.Content {
+		if node.Value != "linters-settings" {
+			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]},
+					},
+				},
+			}
+
+			_, _ = fmt.Fprintf(builder, "### %s\n\n", nodes.Content[i].Value)
+			_, _ = fmt.Fprintln(builder, "```yaml")
+
+			const ident = 2
+			encoder := yaml.NewEncoder(builder)
+			encoder.SetIndent(ident)
+
+			err = encoder.Encode(r)
+			if err != nil {
+				return "", err
+			}
+
+			_, _ = fmt.Fprintln(builder, "```")
+			_, _ = fmt.Fprintln(builder)
+		}
+	}
+
+	return builder.String(), nil
+}
--- a/test/fix_test.go
+++ b/test/fix_test.go
@ -8,7 +8,7 @@ import (
 	"testing"

 	"github.com/stretchr/testify/require"
-	yaml "gopkg.in/yaml.v2"
+	"gopkg.in/yaml.v3"

 	"github.com/golangci/golangci-lint/test/testshared"
 )
--- a/test/linters_test.go
+++ b/test/linters_test.go
@ -10,7 +10,7 @@ import (
 	"testing"

 	"github.com/stretchr/testify/require"
-	"gopkg.in/yaml.v2"
+	"gopkg.in/yaml.v3"

 	"github.com/golangci/golangci-lint/pkg/exitcodes"
 	"github.com/golangci/golangci-lint/test/testshared"
--- a/test/testdata/configs/gomodguard.yml
+++ b/test/testdata/configs/gomodguard.yml
@ -5,7 +5,7 @@ linters-settings:
        - golang.org/x/mod/modfile
    blocked:
      modules:                                                      # List of blocked modules
-        - gopkg.in/yaml.v2:                                         # Blocked module
+        - gopkg.in/yaml.v3:                                         # Blocked module
            recommendations:                                        # Recommended modules that should be used instead (Optional)
              - github.com/kylelemons/go-gypsy                           
            reason: "This is an example of recommendations."        # Reason why the recommended module should be used (Optional)
--- a/test/testdata/gomodguard.go
+++ b/test/testdata/gomodguard.go
@ -6,7 +6,7 @@ import (
 	"log"

 	"golang.org/x/mod/modfile"
-	"gopkg.in/yaml.v2" // ERROR "import of package `gopkg.in/yaml.v2` is blocked because the module is in the blocked modules list. `github.com/kylelemons/go-gypsy` is a recommended module. This is an example of recommendations."
+	"gopkg.in/yaml.v3" // ERROR "import of package `gopkg.in/yaml.v3` is blocked because the module is in the blocked modules list. `github.com/kylelemons/go-gypsy` is a recommended module. This is an example of recommendations."
 )

 // Something just some struct