[release] docs: automatically generate documentation for settings
Write a script to automatically generate settings and command
documentation using the package.json.
Also, delete the smoke-test.md file in the project root. Not sure how it
got there - probably I messed something up while renaming it.
Change-Id: I229f322d6c45bc81a456f5deb534f6591f3917d9
Reviewed-on: https://go-review.googlesource.com/c/vscode-go/+/236963
Reviewed-by: Hyang-Ah Hana Kim <hyangah@gmail.com>
(cherry picked from commit 8a697eea0f74f502ec4f223a94bb9dbc124c113e)
Reviewed-on: https://go-review.googlesource.com/c/vscode-go/+/237159
diff --git a/docs/commands.md b/docs/commands.md
index 932ac5c..251fefe 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -21,175 +21,164 @@
## Detailed list
-<!--TODO(rstambler): Automatically generate this list using the package.json.-->
+<!-- Everything below this line is generated. DO NOT EDIT. -->
-Below is a detailed list of commands. They are categorized into [code editing and generation](#code-editing-and-generation), [testing and benchmarking](#testing-and-benchmarking), [build, lint, and vet](#build-lint-and-vet), [miscellaneous](#miscellaneous), and [troubleshooting](#troubleshooting). You will find the [troubleshooting](#troubleshooting) commands helpful when diagnosing an issue with the extension (learn more in the [Troubleshooting documentation](troubleshooting.md)).
+### `Go: Current GOPATH`
-### Code editing and generation
+See the currently set GOPATH.
-<!--Note: Try to keep this list in roughly alphabetical/logical order.-->
+### `Go: Locate Configured Go Tools`
-#### [`Go: Add Import`](features.md#add-import)
+List all the Go tools being used by this extension along with their locations.
-<!--TODO(rstambler): Confirm exactly how this works.-->
-Manually add an import to your file. See [Add import](features.md#add-import).
+### `Go: Test Function At Cursor`
-#### [`Go: Add Package to Workspace`]
+Runs a unit test at the cursor.
-Add a package to the current workspace.
+### `Go: Subtest At Cursor`
-<!--TODO(rstambler): Figure out how this command works, its use cases, and how it fits into modules.-->
+Runs a sub test at the cursor.
-#### [`Go: Add Tags to Struct Fields`](features.md#add-struct-tags)
+### `Go: Benchmark Function At Cursor`
-Automatically generate [tags](https://pkg.go.dev/reflect?tab=doc#StructTag) for your struct. See [Add or remove struct tags](features.md#add-or-remove-struct-tags).
+Runs a benchmark at the cursor.
-#### [`Go: Remove Tags From Struct Fields`](features.md#add-struct-tags)
+### `Go: Debug Test At Cursor`
-Removes [tags](https://pkg.go.dev/reflect?tab=doc#StructTag) from the selected struct fields. See [Add or remove struct tags](features.md#add-or-remove-struct-tags).
+Debug test at the cursor.
-#### [`Go: Fill struct`](features.md#fill-struct-literals)
+### `Go: Test File`
-Fill a struct literal with default values. See [Fill struct](features.md#fill-struct-literals).
+Runs all unit tests in the current file.
-#### [`Go: Generate Interface Stubs`](features.md#generate-interface-implementation)
+### `Go: Test Package`
-Generate method stubs for given interface. See [Generate interface implementation](features.md#generate-interface-implementation).
+Runs all unit tests in the package of the current file.
-#### [`Go: Generate Unit Tests For Function`](features.md#generate-unit-tests)
+### `Go: Benchmark Package`
-Generate unit tests for the selected function in the current file. See [Generate unit tests](features.md#generate-unit-tests).
+Runs all benchmarks in the package of the current file.
-#### [`Go: Generate Unit Tests For File`](features.md#generate-unit-tests)
+### `Go: Benchmark File`
-Generate unit tests for the current file. See [Generate unit tests](features.md#generate-unit-tests).
+Runs all benchmarks in the current file.
-#### [`Go: Generate Unit Tests For Package`](features.md#generate-unit-tests)
+### `Go: Test All Packages In Workspace`
-Generate unit tests for the current package. See [Generate unit tests](features.md#generate-unit-tests).
+Runs all unit tests from all packages in the current workspace.
-#### [`Go: Extract to function`](features.md#refactor)
+### `Go: Test Previous`
-Extract the highlighted code to a function. Provided by the [`godoctor`](tools.md#godoctor) tool. Learn more about [refactoring](features.md#refactoring).
+Re-runs the last executed test.
-#### [`Go: Extract to variable`](features.md#refactor)
+### `Go: Toggle Test Coverage In Current Package`
-Extract the highlighted code to a local variable. Provided by the [`godoctor`](tools.md#godoctor) tool. Learn more about [refactoring](features.md#refactoring).
+Displays test coverage in the current package.
-### Testing and benchmarking
+### `Go: Generate Unit Tests For Package`
-#### [`Go: Test Function at Cursor`](features.md#test-and-benchmark-in-the-editor)
+Generates unit tests for the current package
-Run the test function at the current cursor position in the file.
+### `Go: Generate Unit Tests For File`
-#### [`Go: Subtest at Cursor`](features.md#test-and-benchmark-in-the-editor)
+Generates unit tests for the current file
-Run the subtest (`t.Run`) at the current cursor position in the file.
+### `Go: Generate Unit Tests For Function`
-#### [`Go: Benchmark Function At Cursor`](features.md#test-and-benchmark-in-the-editor)
+Generates unit tests for the selected function in the current file
-Run the benchmark at the current cursor position in the file.
+### `Go: Generate Interface Stubs`
-#### [`Go: Debug Test At Cursor`](features.md#debugging)
+Generates method stub for implementing the provided interface and inserts at the cursor.
-Debug the test at the current cursor position.
+### `Go: Add Import`
-#### [`Go: Test File`](features.md#test-and-benchmark-in-the-editor)
+Add an import declaration
-Run all of the tests in the current file.
+### `Go: Add Package to Workspace`
-#### [`Go: Benchmark File`](features.md#test-and-benchmark-in-the-editor)
+Add a package from the imports list to the workspace.
-Run all of the benchmarks in the current file.
+### `Go: Install/Update Tools`
-#### [`Go: Test Package`](features.md#test-and-benchmark-in-the-editor)
+install/update the required go packages
-Run all of the tests in the current package.
+### `Go: Toggle Test File`
-#### [`Go: Benchmark Package`](features.md#test-and-benchmark-in-the-editor)
-
-Run all of the benchmarks in the current package.
-
-#### [`Go: Test Previous`](features.md#test-and-benchmark-in-the-editor)
-
-Re-run the most recently executed test command.
+Toggles between file in current active editor and the corresponding test file.
-#### [`Go: Test All Packages In Workspace`](features.md#test-and-benchmark-in-the-editor)
+### `Go: Add Tags To Struct Fields`
-Run all of the tests in the current workspace.
+Add tags configured in go.addTags setting to selected struct using gomodifytags
-#### [`Go: Cancel Running Tests`](features.md#test-and-benchmark-in-the-editor)
+### `Go: Remove Tags From Struct Fields`
-Cancel currently running tests.
+Remove tags configured in go.removeTags setting from selected struct using gomodifytags
-#### [`Go: Toggle Test File`](features.md#toggle-between-code-and-tests)
+### `Go: Fill struct`
-Toggle between a file and its corresponding test file.
+Fill a struct literal with default values
-#### [`Go: Apply Cover Profile`](features.md#code-coverage)
+### `Go: Show All Commands...`
-Apply a given [cover profile](https://blog.golang.org/cover) to the current file.
+Shows all commands from the Go extension in the quick pick
-#### [`Go: Toggle Test Coverage In Current Package`](features.md#code-coverage)
+### `Go: Browse Packages`
-Show [code coverage](features.md#code-coverage) in the current file.
+Browse packages and Go files inside the packages.
-### Build, lint, and vet
+### `Go: Get Package`
-#### [`Go: Build Current Package`](features.md#build-errors)
+Run `go get -v` on the package on the current line.
-Build the current package and show build errors.
+### `Go: Run on Go Playground`
-#### [`Go: Vet Current Package`](features.md#vet-errors)
+Upload the current selection or file to the Go Playground
-Show vet errors for the current package.
+### `Go: Lint Current Package`
-#### [`Go: Lint Current Package`](features.md#lint-errors)
+Run linter in the package of the current file.
-Show lint errors for the current package.
+### `Go: Lint Workspace`
-#### [`Go: Build Workspace`](features.md#build-errors)
+Run linter in the current workspace.
-Build all of the packages in the current workspace and show build errors.
+### `Go: Vet Current Package`
-#### [`Go: Vet Workspace`](features.md#vet-errors)
+Run go vet in the package of the current file.
-Show vet errors for all of the packages in the current workspace.
+### `Go: Vet Workspace`
-#### [`Go: Lint Workspace`](features.md#lint-errors)
+Run go vet in the current workspace.
-Show lint errors for all of the packages in the current workspace.
+### `Go: Build Current Package`
-#### `Go: Install Current Package`
+Build the package of the current file.
-Install the current package and its dependencies.
+### `Go: Build Workspace`
-### Miscellaneous
+Build the current workspace.
-#### [`Go: Restart Language Server`](gopls.md)
+### `Go: Install Current Package`
-Use this command to restart the [language server](gopls.md) without reloading the VS Code window. This can be helpful if something seems goes wrong with the language server (for example, if you see incorrect error messages).
+Install the current package.
-#### [`Go: Run on Go Playground`](features.md#go-playground)
+### `Go: Cancel Running Tests`
-Upload the current selection or file to the Go Playground ([play.golang.org](https://play.golang.org)). See [Go Playground](features.md#go-playground).
+Cancels running tests.
-### Troubleshooting
+### `Go: Apply Cover Profile`
-#### `Go: Current GOPATH`
+Applies existing cover profile.
-See the current value of GOPATH. This is not equivalent to `go env GOPATH`, as your VS Code settings may have altered the value of `GOPATH` used by the extension. This command is helpful when [troubleshooting](troubleshooting.md) the extension.
+### `Go: Extract to function`
-#### [`Go: Install/Update Tools`](tools.md)
+Extract to function using godoctor.
-Install or update the Go tools on which the extension depends. Tools can be installed or updated all at once, or individual tools can be selected.
+### `Go: Extract to variable`
-#### [`Go: Locate Configured Go Tools`](troubleshooting.md#check-your-set-up)
+Extract to variable using godoctor.
-This command is helpful when [troubleshooting](troubleshooting.md) the extension. It prints out the environment variables and paths to the tools used by the extension. See an example of the command's output in the [troubleshooting documentation](troubleshooting.md#check-your-set-up).
+### `Go: Restart Language Server`
-[`golint`]: https://pkg.go.dev/golang.org/x/lint/golint?tab=overview
-[`staticcheck`]: https://pkg.go.dev/honnef.co/go/tools/staticcheck?tab=overview
-[`golangci-lint`]: https://golangci-lint.run/
-[`revive`]: https://pkg.go.dev/github.com/mgechev/revive?tab=overview
-[`gomodifytags`]: tools.md#gomodifytags
+Restart the running instance of the language server
diff --git a/docs/settings.md b/docs/settings.md
index dd328a8..591b180 100644
--- a/docs/settings.md
+++ b/docs/settings.md
@@ -19,25 +19,212 @@
## Detailed list
-A list of popular and notable settings can be found below.
+<!-- Everything below this line is generated. DO NOT EDIT. -->
-* [docsTool](#docsTool)
-* [formatTool](#formatTool)
-* [lintTool](#lintTool)
-* [lintFlags](#lintFlags)
+### `go.addTags`
-### docsTool
+Tags and options configured here will be used by the Add Tags command to add tags to struct fields. If promptForTags is true, then user will be prompted for tags and options. By default, json tags are added.
-One of `"godoc"`, `"gogetdoc"`, or `"guru"` (`gogetdoc` is the default). This is the tool used by the [go to definition](features.md#go-to-definition), [signature help](features.md#signature-help), and [quick info on hover](features.md#quick-info-on-hover) features. See more information about each of these tools in the [Documentation](tools.md#Documentation) section.
+### `go.alternateTools`
-### formatTool
+Alternate tools or alternate paths for the same tools used by the Go extension. Provide either absolute path or the name of the binary in GOPATH/bin, GOROOT/bin or PATH. Useful when you want to use wrapper script for the Go tools or versioned tools from https://gopkg.in.
-One of `"gofmt"`, `"goimports"`, `"goreturns"`, and `"goformat"` (`goreturns` is the default). This is the tool used by the [formatting and import organization](features.md#formatting-and-import-organization) features. See more information about each of these tools in the [Formatting](tools.md#Formatting) section.
+### `go.autocompleteUnimportedPackages`
-### lintTool
+Include unimported packages in auto-complete suggestions.
-One of `"golint"`, `"staticcheck"`, `"golangci-lint"`, and `"revive"` (`golint` is the default). This is the tool used by the [lint-on-save](features.md#lint-on-save) feature. See more information about each of these tools in the [Diagnostics](tools.md#Diagnostics) section.
+### `go.buildFlags`
-### lintFlags
+Flags to `go build`/`go test` used during build-on-save or running tests. (e.g. ["-ldflags='-s'"])
-This setting can be used to pass additional flags to your lint tool of choice.
+### `go.buildOnSave`
+
+Compiles code on file save using 'go build -i' or 'go test -c -i'. Options are 'workspace', 'package', or 'off'.
+
+### `go.buildTags`
+
+The Go build tags to use for all commands, that support a `-tags '...'` argument. When running tests, go.testTags will be used instead if it was set.
+
+### `go.coverOnSave`
+
+If true, runs 'go test -coverprofile' on save and shows test coverage.
+
+### `go.coverOnSingleTest`
+
+If true, shows test coverage when Go: Test Function at cursor command is run.
+
+### `go.coverOnSingleTestFile`
+
+If true, shows test coverage when Go: Test Single File command is run.
+
+### `go.coverOnTestPackage`
+
+If true, shows test coverage when Go: Test Package command is run.
+
+### `go.coverageDecorator`
+
+This option lets you choose the way to display code coverage. Choose either to highlight the complete line or to show a decorator in the gutter. You can customize the color for the former and the style for the latter.
+
+### `go.coverageOptions`
+
+Use these options to control whether only covered or only uncovered code or both should be highlighted after running test coverage
+
+### `go.delveConfig`
+
+Delve settings that applies to all debugging sessions. Debug configuration in the launch.json file will override these values.
+
+### `go.docsTool`
+
+Pick 'godoc' or 'gogetdoc' to get documentation. Not applicable when using the language server.
+
+### `go.editorContextMenuCommands`
+
+Experimental Feature: Enable/Disable entries from the context menu in the editor.
+
+### `go.enableCodeLens`
+
+Feature level setting to enable/disable code lens for references and run/debug tests
+
+### `go.formatFlags`
+
+Flags to pass to format tool (e.g. ["-s"])
+
+### `go.formatTool`
+
+Pick 'gofmt', 'goimports', 'goreturns' or 'goformat' to run on format. Not applicable when using the language server. Choosing 'goimports' or 'goreturns' will add missing imports and remove unused imports.
+
+### `go.generateTestsFlags`
+
+Additional command line flags to pass to `gotests` for generating tests.
+
+### `go.gocodeAutoBuild`
+
+Enable gocode's autobuild feature. Not applicable when using the language server.
+
+### `go.gocodeFlags`
+
+Additional flags to pass to gocode. Not applicable when using the language server.
+
+### `go.gocodePackageLookupMode`
+
+Used to determine the Go package lookup rules for completions by gocode. Only applies when using nsf/gocode. Latest versions of the Go extension uses mdempsky/gocode by default. Not applicable when using the language server.
+
+### `go.gopath`
+
+Specify GOPATH here to override the one that is set as environment variable. The inferred GOPATH from workspace root overrides this, if go.inferGopath is set to true.
+
+### `go.goroot`
+
+Specifies the GOROOT to use when no environment variable is set.
+
+### `go.gotoSymbol.ignoreFolders`
+
+Folder names (not paths) to ignore while using Go to Symbol in Workspace feature
+
+### `go.gotoSymbol.includeGoroot`
+
+If false, the standard library located at $GOROOT will be excluded while using the Go to Symbol in File feature
+
+### `go.gotoSymbol.includeImports`
+
+If false, the import statements will be excluded while using the Go to Symbol in File feature
+
+### `go.inferGopath`
+
+Infer GOPATH from the workspace root.
+
+### `go.installDependenciesWhenBuilding`
+
+If true, then `-i` flag will be passed to `go build` everytime the code is compiled.
+
+### `go.languageServerExperimentalFeatures`
+
+Use this setting to enable/disable experimental features from the language server.
+
+### `go.languageServerFlags`
+
+Flags like -rpc.trace and -logfile to be used while running the language server.
+
+### `go.lintFlags`
+
+Flags to pass to Lint tool (e.g. ["-min_confidence=.8"])
+
+### `go.lintOnSave`
+
+Lints code on file save using the configured Lint tool. Options are 'file', 'package', 'workspace' or 'off'.
+
+### `go.lintTool`
+
+Specifies Lint tool name.
+
+### `go.liveErrors`
+
+Use gotype on the file currently being edited and report any semantic or syntactic errors found after configured delay.
+
+### `go.playground`
+
+
+
+### `go.removeTags`
+
+Tags and options configured here will be used by the Remove Tags command to remove tags to struct fields. If promptForTags is true, then user will be prompted for tags and options. By default, all tags and options will be removed.
+
+### `go.testEnvFile`
+
+Absolute path to a file containing environment variables definitions. File contents should be of the form key=value.
+
+### `go.testEnvVars`
+
+Environment variables that will passed to the process that runs the Go tests
+
+### `go.testFlags`
+
+Flags to pass to `go test`. If null, then buildFlags will be used.
+
+### `go.testOnSave`
+
+Run 'go test' on save for current package. It is not advised to set this to `true` when you have Auto Save enabled.
+
+### `go.testTags`
+
+The Go build tags to use for when running tests. If null, then buildTags will be used.
+
+### `go.testTimeout`
+
+Specifies the timeout for go test in ParseDuration format.
+
+### `go.toolsEnvVars`
+
+Environment variables that will passed to the processes that run the Go tools (e.g. CGO_CFLAGS)
+
+### `go.toolsGopath`
+
+Location to install the Go tools that the extension depends on if you don't want them in your GOPATH.
+
+### `go.trace.server`
+
+Trace the communication between VS Code and the Go language server.
+
+### `go.useCodeSnippetsOnFunctionSuggest`
+
+Complete functions with their parameter signature, including the variable types
+
+### `go.useCodeSnippetsOnFunctionSuggestWithoutType`
+
+Complete functions with their parameter signature, excluding the variable types
+
+### `go.useGoProxyToCheckForToolUpdates`
+
+When enabled, the extension automatically checks the Go proxy if there are updates available for the Go tools (at present, only gopls) it depends on and prompts the user accordingly
+
+### `go.useLanguageServer`
+
+Use the Go language server "gopls" from Google for powering language features like code navigation, completion, formatting & diagnostics.
+
+### `go.vetFlags`
+
+Flags to pass to `go tool vet` (e.g. ["-all", "-shadow"])
+
+### `go.vetOnSave`
+
+Vets code on file save using 'go tool vet'. Options are 'workspace', 'package or 'off'.
diff --git a/tools/generate.go b/tools/generate.go
new file mode 100644
index 0000000..6dc6745
--- /dev/null
+++ b/tools/generate.go
@@ -0,0 +1,111 @@
+// Copyright 2020 The Go Authors. All rights reserved.
+// Licensed under the MIT License.
+// See LICENSE in the project root for license information.
+
+// Command generate is used to generate documentation from the package.json.
+package main
+
+import (
+ "bytes"
+ "encoding/json"
+ "fmt"
+ "io/ioutil"
+ "log"
+ "os"
+ "path/filepath"
+ "sort"
+)
+
+type PackageJSON struct {
+ Contributes struct {
+ Commands []Command `json:"commands,omitempty"`
+ Configuration struct {
+ Properties map[string]Property `json:"properties,omitempty"`
+ } `json:"configuration,omitempty"`
+ } `json:"contributes,omitempty"`
+}
+
+type Command struct {
+ Command string `json:"command,omitempty"`
+ Title string `json:"title,omitempty"`
+ Description string `json:"description,omitempty"`
+}
+
+type Property struct {
+ Name string
+
+ Default interface{} `json:"default,omitempty"`
+ Description string `json:"description,omitempty"`
+ Type interface{} `json:"type,omitempty"`
+}
+
+func main() {
+ // Assume this is running from the vscode-go directory.
+ dir, err := os.Getwd()
+ if err != nil {
+ log.Fatal(err)
+ }
+ if filepath.Base(dir) != "vscode-go" {
+ log.Fatalf("run this script from the vscode-go root directory")
+ }
+ // Find the package.json file.
+ data, err := ioutil.ReadFile(filepath.Join(dir, "package.json"))
+ if err != nil {
+ log.Fatal(err)
+ }
+ pkgJSON := &PackageJSON{}
+ if err := json.Unmarshal(data, pkgJSON); err != nil {
+ log.Fatal(err)
+ }
+ rewrite := func(filename string, toAdd []byte) {
+ content, err := ioutil.ReadFile(filename)
+ if err != nil {
+ log.Fatal(err)
+ }
+ gen := []byte(`<!-- Everything below this line is generated. DO NOT EDIT. -->`)
+ split := bytes.Split(content, gen)
+ if len(split) == 1 {
+ log.Fatalf("expected to find %q in %s, not found", filename, gen)
+ }
+ s := bytes.Join([][]byte{
+ bytes.TrimSpace(split[0]),
+ gen,
+ toAdd,
+ }, []byte("\n\n"))
+ if err := ioutil.WriteFile(filename, append(s, '\n'), 0644); err != nil {
+ log.Fatal(err)
+ }
+ fmt.Printf("regenerated %s\n", filename)
+ }
+ var b bytes.Buffer
+ for i, c := range pkgJSON.Contributes.Commands {
+ b.WriteString(fmt.Sprintf("### `%s`\n\n%s", c.Title, c.Description))
+ if i != len(pkgJSON.Contributes.Commands)-1 {
+ b.WriteString("\n\n")
+ }
+ }
+ rewrite(filepath.Join(dir, "docs", "commands.md"), b.Bytes())
+
+ // Clear so that we can rewrite settings.md.
+ b.Reset()
+
+ var properties []Property
+ for name, p := range pkgJSON.Contributes.Configuration.Properties {
+ properties = append(properties, Property{
+ Name: name,
+ Default: p.Default,
+ Description: p.Description,
+ Type: p.Type,
+ })
+ }
+ sort.Slice(properties, func(i, j int) bool {
+ return properties[i].Name < properties[j].Name
+ })
+ for i, p := range properties {
+ b.WriteString(fmt.Sprintf("### `%s`\n\n%s", p.Name, p.Description))
+ if i != len(properties)-1 {
+ b.WriteString("\n\n")
+ }
+ }
+ rewrite(filepath.Join(dir, "docs", "settings.md"), b.Bytes())
+}
