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

Author: ldez

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

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>
               ))}

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).

docs/src/docs/usage/linters.mdx

@@ -15,3 +15,7 @@ golangci-lint help linters
 ## Disabled By Default Linters (`-E/--enable`)
 
 {.DisabledByDefaultLinters}
+
+## Linters Configuration
+
+{ .LintersExample }

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

go.sum

@@ -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
+}

scripts/expand_website_templates/main.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"
 )

test/fix_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"

test/linters_test.go

@@ -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)

test/testdata/configs/gomodguard.yml

@@ -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