/* Copyright 2021 Google LLC Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at https://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. */ // Documentation generator package main import ( "bytes" "flag" "fmt" "io/ioutil" "os" "sort" "strings" "github.com/bazelbuild/buildtools/warn" "github.com/golang/protobuf/proto" docspb "github.com/bazelbuild/buildtools/warn/docs/proto" ) func readWarningsFromFile(path string) (*docspb.Warnings, error) { content, err := ioutil.ReadFile(path) if err != nil { return nil, err } warnings := &docspb.Warnings{} if err := proto.UnmarshalText(string(content), warnings); err != nil { return nil, err } return warnings, nil } func isExistingWarning(name string) bool { for _, n := range warn.AllWarnings { if n == name { return true } } return false } func isDisabledWarning(name string) bool { if !isExistingWarning(name) { return false } for _, n := range warn.DefaultWarnings { if n == name { return false } } return true } func generateWarningsDocs(warnings *docspb.Warnings) string { var b bytes.Buffer b.WriteString(`# Buildifier warnings Warning categories supported by buildifier's linter: `) // Table of contents var names []string for _, w := range warnings.Warnings { names = append(names, w.Name...) } sort.Strings(names) for _, n := range names { fmt.Fprintf(&b, " * [`%s`](#%s)\n", n, n) } // Misc b.WriteString(` ### How to disable warnings All warnings can be disabled / suppressed / ignored by adding a special comment ` + "`" + `# buildifier: disable=` + "`" + ` to the expression that causes the warning. Historically comments with ` + "`" + `buildozer` + "`" + ` instead of ` + "`" + `buildifier` + "`" + ` are also supported, they are equivalent. #### Examples ` + "```" + `python # buildifier: disable=no-effect """ A multiline comment as a string literal. Docstrings don't trigger the warning if they are first statements of a file or a function. """ if debug: print("Debug information:", foo) # buildifier: disable=print ` + "```\n") // Individual warnings sort.Slice(warnings.Warnings, func(i, j int) bool { return strings.Compare(warnings.Warnings[i].Name[0], warnings.Warnings[j].Name[0]) < 0 }) for _, w := range warnings.Warnings { // Header b.WriteString("\n--------------------------------------------------------------------------------\n\n## ") for _, n := range w.Name { fmt.Fprintf(&b, "", n) } fmt.Fprintf(&b, "%s\n\n", w.Header) // Name(s) if len(w.Name) == 1 { fmt.Fprintf(&b, " * Category name: `%s`\n", w.Name[0]) } else { b.WriteString(" * Category names:\n") for _, n := range w.Name { fmt.Fprintf(&b, " * `%s`\n", n) } } // Bazel --incompatible flag if w.BazelFlag != "" { label := fmt.Sprintf("`%s`", w.BazelFlag) if w.BazelFlagLink != "" { label = fmt.Sprintf("[%s](%s)", label, w.BazelFlagLink) } fmt.Fprintf(&b, " * Flag in Bazel: %s\n", label) } // Automatic fix fix := "no" if w.Autofix { fix = "yes" } fmt.Fprintf(&b, " * Automatic fix: %s\n", fix) // Disabled by default if isDisabledWarning(w.Name[0]) { b.WriteString(" * [Disabled by default](buildifier/README.md#linter)\n") } // Non-existent if !isExistingWarning(w.Name[0]) { b.WriteString(" * Not supported by the latest version of Buildifier\n") } // Suppress the warning b.WriteString(" * [Suppress the warning](#suppress): ") for i, n := range w.Name { if i != 0 { b.WriteString(", ") } fmt.Fprintf(&b, "`# buildifier: disable=%s`", n) } b.WriteString("\n") // Description fmt.Fprintf(&b, "\n%s\n", w.Description) } return b.String() } func writeWarningsDocs(docs, path string) error { f, err := os.Create(path) if err != nil { return err } if _, err := f.WriteString(docs); err != nil { return err } return f.Close() } func main() { flag.Parse() warnings, err := readWarningsFromFile(flag.Arg(0)) if err != nil { fmt.Fprintln(os.Stderr, err) os.Exit(1) } docs := generateWarningsDocs(warnings) if err := writeWarningsDocs(docs, flag.Arg(1)); err != nil { fmt.Fprintln(os.Stderr, err) os.Exit(1) } }