README.md: use wiki links instead of blob/master/docs
And change the use of https://github.com/golang/vscode-go/blob/master/docs
from files in docs directory to relative paths so tools like
docs2wiki can translate them consistently.
Fixes golang/vscode-go#2094
Change-Id: I185f590d3d48704d648edcf4ad58b9aee5414690
Reviewed-on: https://go-review.googlesource.com/c/vscode-go/+/412057
Reviewed-by: Jamal Carvalho <jamal@golang.org>
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
index 3e85b56..e54406b 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -13,8 +13,8 @@
- [`#vscode` channel in Gophers Slack](https://invite.slack.golangbridge.org/messages/vscode)
Before filing an issue, please review our troubleshooting guides
-* [Troubleshooting problems with debugging](https://github.com/golang/vscode-go/blob/master/docs/debugging.md#troubleshooting)
-* [Troubleshooting other problems](https://github.com/golang/vscode-go/tree/master/docs/troubleshooting.md)
+* [Troubleshooting problems with debugging](https://github.com/golang/vscode-go/wiki/debugging#troubleshooting)
+* [Troubleshooting other problems](https://github.com/golang/vscode-go/wiki/troubleshooting)
Please answer these questions before submitting your issue. Thanks!
-->
diff --git a/README.md b/README.md
index 7e18d2d..a96896f 100644
--- a/README.md
+++ b/README.md
@@ -9,9 +9,9 @@
[Go programming language](https://golang.org/).
📣
-[Remote attach debugging](docs/debugging.md#connecting-to-headless-delve-with-target-specified-at-server-start-up) is now available via Delve's native DAP implementation with Delve v1.7.3 or newer. It enchances remote debugging with the same
-[debugging features](docs/debugging.md) that are already in use for local debugging. It is now the default with the
-[Go Nightly](docs/nightly.md) build of the extension and will become the default for the stable releases in mid 2022.
+[Remote attach debugging](https://github.com/golang/vscode-go/wiki/debugging#connecting-to-headless-delve-with-target-specified-at-server-start-up) is now available via Delve's native DAP implementation with Delve v1.7.3 or newer. It enchances remote debugging with the same
+[debugging features](https://github.com/golang/vscode-go/wiki/debugging) that are already in use for local debugging. It is now the default with the
+[Go Nightly](https://github.com/golang/vscode-go/wiki/nightly) build of the extension and will become the default for the stable releases in mid 2022.
We recommend switching your remote attach configurations in `launch.json` to use
`"debugAdapter":"dlv-dap"` now to verify that this works for you.
Please [file a new issue](https://github.com/golang/vscode-go/issues/new/choose) if you encounter any problems.
@@ -29,7 +29,7 @@
* [Go installation guide]. This extension works best with Go 1.14+.
* [Managing extensions in VS Code].
* **Step 2.** To activate the extension, open any directory or workspace
- containing Go code. Once activated, the [Go status bar](docs/ui.md) will
+ containing Go code. Once activated, the [Go status bar](https://github.com/golang/vscode-go/wiki/ui) will
appear in the bottom left corner of the window and show the recognized Go
version.
* **Step 3.** The extension depends on [a set of extra command-line tools](#tools).
@@ -46,7 +46,7 @@
Please be sure to learn more about the many [features](#features) of this
extension, as well as how to [customize](#customization) them. Take a look at
-[Troubleshooting](docs/troubleshooting.md) and [Help](#ask-for-help) for further
+[Troubleshooting](https://github.com/golang/vscode-go/wiki/troubleshooting) and [Help](#ask-for-help) for further
guidance.
If you are new to Go, [this article](https://golang.org/doc/code.html) provides
@@ -72,7 +72,7 @@
commands for working with Go files. You can access any of these by opening the
Command Palette (`Ctrl+Shift+P` on Linux/Windows and `Cmd+Shift+P` on Mac), and
then typing in the command name. See the
-[full list of commands](docs/commands.md#detailed-list) provided by this
+[full list of commands](https://github.com/golang/vscode-go/wiki/commands#detailed-list) provided by this
extension.
<p align=center>
@@ -85,7 +85,7 @@
For better syntax highlighting, we recommend enabling
[semantic highlighting](https://code.visualstudio.com/api/language-extensions/semantic-highlight-guide)
-by turning on [Gopls' `ui.semanticTokens` setting](https://github.com/golang/vscode-go/blob/master/docs/settings.md#uisemantictokens).
+by turning on [Gopls' `ui.semanticTokens` setting](https://github.com/golang/vscode-go/wiki/settings#uisemantictokens).
```
"gopls": { "ui.semanticTokens": true }
```
@@ -94,7 +94,7 @@
The extension uses a few command-line tools developed by the Go community. In
particular, `go`, `gopls`, and `dlv` **must** be installed for this extension
-to work correctly. See the [tools documentation](docs/tools.md) for a complete
+to work correctly. See the [tools documentation](https://github.com/golang/vscode-go/wiki/tools) for a complete
list of tools the extension depends on.
In order to locate these command-line tools, the extension searches
@@ -128,16 +128,16 @@
The extension needs no configuration and should work out of the box. However,
you may wish to adjust settings to customize its behavior. Please see the
-[settings documentation](docs/settings.md) for a comprehensive list of settings.
-See [advanced topics](docs/advanced.md) for further customizations and unique
+[settings documentation](https://github.com/golang/vscode-go/wiki/settings) for a comprehensive list of settings.
+See [advanced topics](https://github.com/golang/vscode-go/wiki/advanced) for further customizations and unique
use cases.
## Troubleshooting
If the extension isn't working as you expect, you can take a look at our
troubleshooting guides. There is one for [general
-troubleshooting](docs/troubleshooting.md), and another specifically for
-[troubleshooting the debugging feature](docs/debugging.md#troubleshooting).
+troubleshooting](https://github.com/golang/vscode-go/wiki/troubleshooting), and another specifically for
+[troubleshooting the debugging feature](https://github.com/golang/vscode-go/wiki/debugging#troubleshooting).
## Ask for help
@@ -154,13 +154,13 @@
If you'd like to get early access to new features and bug fixes, you can use the
nightly build of this extension. Learn how to install it in by reading the
-[Go Nightly documentation](docs/nightly.md).
+[Go Nightly documentation](https://github.com/golang/vscode-go/wiki/nightly).
## Contributing
We welcome your contributions and thank you for working to improve the Go
development experience in VS Code. If you would like to help work on the VS Code
-Go extension, please see our [contribution guide](docs/contributing.md). It
+Go extension, please see our [contribution guide](https://github.com/golang/vscode-go/wiki/contributing). It
explains how to build and run the extension locally, and describes the process
of sending a contribution.
@@ -181,14 +181,14 @@
[VS Code Go extension]: https://marketplace.visualstudio.com/items?itemName=golang.go
[Go installation guide]: https://golang.org/doc/install
["Getting started with VS Code Go"]: https://youtu.be/1MXIGYrMk80
-[IntelliSense]: https://github.com/golang/vscode-go/blob/master/docs/features.md#intellisense
-[code navigation]: https://github.com/golang/vscode-go/blob/master/docs/features.md#code-navigation
-[code editing]: https://github.com/golang/vscode-go/blob/master/docs/features.md#code-editing
-[diagnostics]: https://github.com/golang/vscode-go/blob/master/docs/features.md#diagnostics
-[testing]: https://github.com/golang/vscode-go/blob/master/docs/features.md##run-and-test-in-the-editor
-[debugging]: https://github.com/golang/vscode-go/blob/master/docs/debugging.md#features
-[full feature breakdown]: https://github.com/golang/vscode-go/blob/master/docs/features.md
+[IntelliSense]: https://github.com/golang/vscode-go/wiki/features#intellisense
+[code navigation]: https://github.com/golang/vscode-go/wiki/features#code-navigation
+[code editing]: https://github.com/golang/vscode-go/wiki/features#code-editing
+[diagnostics]: https://github.com/golang/vscode-go/wiki/features#diagnostics
+[testing]: https://github.com/golang/vscode-go/wiki/features#run-and-test-in-the-editor
+[debugging]: https://github.com/golang/vscode-go/wiki/debugging#features
+[full feature breakdown]: https://github.com/golang/vscode-go/wiki/features
[workspace documentation]: https://github.com/golang/tools/blob/master/gopls/doc/workspace.md
-[`Go: Install/Update Tools` command]: https://github.com/golang/vscode-go/blob/master/docs/commands.md#go-installupdate-tools
+[`Go: Install/Update Tools` command]: https://github.com/golang/vscode-go/wiki/commands#go-installupdate-tools
[documentation about supported workspace layouts]: https://github.com/golang/tools/blob/master/gopls/doc/workspace.md
[Workspace Folders]: https://code.visualstudio.com/docs/editor/multi-root-workspaces
diff --git a/docs/debugging.md b/docs/debugging.md
index 2304d3f..bd53164 100644
--- a/docs/debugging.md
+++ b/docs/debugging.md
@@ -6,7 +6,7 @@
The Go extension has been communicating with Delve through a custom debug adapter program (`legacy` mode).
As the new [`Delve`'s native debug adapter implementation](https://github.com/go-delve/delve/tree/master/service/dap) has become available (since Delve v1.6.1), the Go extension is transitioning to deprecate the legacy debug adapter in favor of direct communication with Delve via [DAP](https://microsoft.github.io/debug-adapter-protocol/overview).
- 📣 **We are happy to announce that the new _`dlv-dap`_ mode of Delve integration is enabled for _local_ _debugging_ by default. For [_remote_ _debugging_](#remote-debugging) it is the default in [Go Nightly](docs/nightly.md) and is
+ 📣 **We are happy to announce that the new _`dlv-dap`_ mode of Delve integration is enabled for _local_ _debugging_ by default. For [_remote_ _debugging_](#remote-debugging) it is the default in [Go Nightly](nightly.md) and is
available with stable builds on demand with `"debugAdapter": "dlv-dap"` attribute in `launch.json` or `settings.json`!**
Many features and settings described in this document may be available only with the new `dlv-dap` mode.
@@ -39,7 +39,7 @@
Once `dlv` is installed on your system, the extension will prompt you for update whenever installing a newer version is necessary (usually after the Go extension upgrade). You can set the `go.toolsManagement.autoUpdate` setting so the extension can update `dlv` automatically for you.
-If you need to install `dlv` manually outside of VS Code (for example, you are building a dev container with necessary tools preinstalled, or install `dlv` built from the tree head), follow the instruction in [Manually installing `dlv`](https://github.com/golang/vscode-go/blob/master/docs/debugging.md#manually-installing-dlv).
+If you need to install `dlv` manually outside of VS Code (for example, you are building a dev container with necessary tools preinstalled, or install `dlv` built from the tree head), follow the instruction in [Manually installing `dlv`](debugging.md#manually-installing-dlv).
💡 The extension used to install a dev version of `dlv` as a separate binary (known as `dlv-dap`). As Delve DAP is stable and the transition work is near completion, from v0.31.0 (to be released in Jan 2022), the extension will switch to use `dlv`, instead of the `dlv-dap` binary. It is safe to delete `dlv-dap` installed on the system after v0.31.0 release.
@@ -341,7 +341,7 @@
<p align="center"><img src="images/vscode-go-debug-arch.png" alt="vscode-go debug architecture"> </p>
-For information on debugging using the legacy debug adapter, please see the old [Debugging Documentation](https://github.com/golang/vscode-go/blob/master/docs/debugging.md). Note that many new or enhanced features discussed in this document may not be available with the legacy debug adapter.
+For information on debugging using the legacy debug adapter, please see the old [Debugging Documentation](debugging.md). Note that many new or enhanced features discussed in this document may not be available with the legacy debug adapter.
### Handling STDIN
@@ -489,7 +489,7 @@
On rare occasions, you may want to install `dlv` by yourself instead of letting the extension handle its installation.
-First, find where the Go extension finds tools. Like [other tools the extension uses](https://github.com/golang/vscode-go/blob/master/docs/tools.md#tools), the Go extension searches the `dlv` executable from `${GOPATH}/bin`, `${GOBIN}` and `${PATH}` (or `Path` in Windows). So, install `dlv` in the directory. The easiest way to check the tool installation location the Go extension uses is currently by running the `Go: Locate Configured Go Tools` command from the command palette (⇧+⌘+P or Ctrl+Shift+P).
+First, find where the Go extension finds tools. Like [other tools the extension uses](tools.md#tools), the Go extension searches the `dlv` executable from `${GOPATH}/bin`, `${GOBIN}` and `${PATH}` (or `Path` in Windows). So, install `dlv` in the directory. The easiest way to check the tool installation location the Go extension uses is currently by running the `Go: Locate Configured Go Tools` command from the command palette (⇧+⌘+P or Ctrl+Shift+P).
If your Go version is 1.16 or newer:
@@ -529,7 +529,7 @@
The [headless dlv server](https://github.com/go-delve/delve/tree/master/Documentation/api) can now be used with both `"debugAdapter": "legacy"` (default value) and `"debugAdapter": "dlv-dap"` (with Delve v1.7.3 or newer) as well as Delve's [command-line interface](https://github.com/go-delve/delve/tree/master/Documentation/cli) via `dlv connect`. The `--accept-multiclient` flag makes this a multi-use server that persists on `Disconnect` from a client and allows repeated connections from any of the aforementioned clients. A combination of `--accept-multiclient --continue` flags can be used to resume process execution on start-up. Please see `dlv --help` and `dlv [command] --help` for dlv's command-line options.
-We encourage you to give the newly added `"debugAdapter": "dlv-dap"` support a try and to [let us know of any issues](https://github.com/golang/vscode-go/issues/new). If you need to use the `legacy` mode, pleasse also see the [legacy remote debugging](https://github.com/golang/vscode-go/blob/master/docs/debugging-legacy.md#remote-debugging) documentation.
+We encourage you to give the newly added `"debugAdapter": "dlv-dap"` support a try and to [let us know of any issues](https://github.com/golang/vscode-go/issues/new). If you need to use the `legacy` mode, pleasse also see the [legacy remote debugging](debugging-legacy.md#remote-debugging) documentation.
For example, start external headless server:
```
@@ -611,9 +611,9 @@
1. Read documentation and [FAQs](#faqs). Also check the [Delve FAQ](https://github.com/go-delve/delve/blob/master/Documentation/faq.md) in case the problem is mentioned there.
1. Check your `launch.json` configuration. Often error messages appearing in the DEBUG CONSOLE panel reveal issues.
-1. Update Delve (`dlv`) to pick up most recent bug fixes. Follow [the instruction](https://github.com/golang/vscode-go/blob/master/docs/debugging.md#staying-up-to-date).
+1. Update Delve (`dlv`) to pick up most recent bug fixes. Follow [the instruction](debugging.md#staying-up-to-date).
1. Check if you can reproduce the issue with `dlv`, the command line tool from the integrated terminal. <!-- TODO(vscode-go): add instructions https://github.com/golang/vscode-go/issues/1931 --> If it's reproducible when using `dlv`, take a look at the [Delve project issue tracker](https://github.com/go-delve/delve/issues).
-1. Capture [logs](https://github.com/golang/vscode-go/blob/master/docs/debugging.md#collecting-logs) and inspect them.
+1. Capture [logs](debugging.md#collecting-logs) and inspect them.
1. Look at the [existing debugging issues](https://github.com/golang/vscode-go/labels/Debug) if similar issues were reported.
1. If none of these solve your problem, please [open a new issue](#reporting-issues).
@@ -651,7 +651,7 @@
### Debug sessions started with the "debug test" CodeLens or the test UI does not use my `launch.json` configuration.
-The "debug test" CodeLens and the [test UI](https://github.com/golang/vscode-go/blob/master/docs/features.md#test-and-benchmark) do not use the `launch.json` configuration ([Issue 855](https://github.com/golang/vscode-go/issues/855)). As a workaround, use the `go.delveConfig` setting and the `go.testFlags` setting. Please note that these all apply to all debug sessions unless overwritten by a specific `launch.json` configuration.
+The "debug test" CodeLens and the [test UI](features.md#test-and-benchmark) do not use the `launch.json` configuration ([Issue 855](https://github.com/golang/vscode-go/issues/855)). As a workaround, use the `go.delveConfig` setting and the `go.testFlags` setting. Please note that these all apply to all debug sessions unless overwritten by a specific `launch.json` configuration.
### Starting a debug session fails with `decoding dwarf section info at offset 0x0: too short` or `could not open debug info` error.
@@ -692,7 +692,7 @@
The core part of Delve DAP implementation is in the [`service/dap`](https://github.com/go-delve/delve/tree/master/service/dap) package. Follow Delve project's [contribution guideline](https://github.com/go-delve/delve/blob/master/CONTRIBUTING.md#contributing-code) to send PRs.
-Code for integration with the Go extension is mostly in [`src/goDebugFactory.ts`](https://github.com/golang/vscode-go/blob/master/src/goDebugFactory.ts) and tests are in [`test/integration/goDebug.test.ts`](https://github.com/golang/vscode-go/blob/master/test/integration/goDebug.test.ts). Please take a look at VS Code Go project's [contribution guideline](https://github.com/golang/vscode-go/blob/master/docs/contributing.md) to learn about how to prepare a change and send it for review.
+Code for integration with the Go extension is mostly in [`src/goDebugFactory.ts`](https://github.com/golang/vscode-go/blob/master/src/goDebugFactory.ts) and tests are in [`test/integration/goDebug.test.ts`](https://github.com/golang/vscode-go/blob/master/test/integration/goDebug.test.ts). Please take a look at VS Code Go project's [contribution guideline](contributing.md) to learn about how to prepare a change and send it for review.
### Testing
diff --git a/docs/faq.md b/docs/faq.md
index 204e117..85bd464 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -10,7 +10,7 @@
For better syntax highlighting (including generics support), we recommend enabling
[semantic highlighting](https://code.visualstudio.com/api/language-extensions/semantic-highlight-guide)
-by turning on [Gopls' `ui.semanticTokens` setting](https://github.com/golang/vscode-go/blob/master/docs/settings.md#uisemantictokens).
+by turning on [Gopls' `ui.semanticTokens` setting](settings.md#uisemantictokens).
```json
"gopls": { "ui.semanticTokens": true }
diff --git a/docs/features.md b/docs/features.md
index e658933..32601d8 100644
--- a/docs/features.md
+++ b/docs/features.md
@@ -129,9 +129,9 @@
Format code and organize imports, either manually or on save.
-The extension formats Go code, organizes imports, and removes unused imports by default. For different behavior, please override per-language default settings following [the instruction](https://github.com/golang/vscode-go/blob/master/docs/advanced.md#formatting-code-and-organizing-imports).
+The extension formats Go code, organizes imports, and removes unused imports by default. For different behavior, please override per-language default settings following [the instruction](advanced.md#formatting-code-and-organizing-imports).
-When organizing imports, the imported packages are grouped in the default `goimports` style. In order to group some packages after 3rd-party packages, use [`"gopls": { "formatting.local": <comma-separated imports prefix>}`](https://github.com/golang/vscode-go/blob/master/docs/settings.md#formattinglocal).
+When organizing imports, the imported packages are grouped in the default `goimports` style. In order to group some packages after 3rd-party packages, use [`"gopls": { "formatting.local": <comma-separated imports prefix>}`](settings.md#formattinglocal).
#### Add import
diff --git a/docs/settings.md b/docs/settings.md
index 1370d64..cdb61ac 100644
--- a/docs/settings.md
+++ b/docs/settings.md
@@ -4,7 +4,7 @@
To navigate to your settings, open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P) and search for "settings". The simplest way to modify your settings is through "Preferences: Open Settings (UI)".
-For tuning the features provided by `gopls`, see the [section](https://github.com/golang/vscode-go/blob/master/docs/settings.md#settings-for-gopls) for `gopls` settings.
+For tuning the features provided by `gopls`, see the [section](settings.md#settings-for-gopls) for `gopls` settings.
## Latest changes
diff --git a/docs/tools.md b/docs/tools.md
index bbb3c35..a866e97 100644
--- a/docs/tools.md
+++ b/docs/tools.md
@@ -18,7 +18,7 @@
### [`gopls`]
[`gopls`] is the official Go [language server](https://langserver.org/) developed by the Go team. It is the default backend for most of this extension's IntelliSense, code navigation, code editing, and diagnostics features. When the extension starts, it spawns a `gopls` instance in server mode for each VS Code project.
-`gopls` uses the `go` command to analyze your code. The extension automatically propagates necessary settings such as `"go.buildFlags"`, `"go.buildTags"`, `"go.toolsEnvVars"` and the path to the right `go` command to `gopls`. No extra settings should be necessary, but when you need to adjust `gopls`'s behavior further (e.g., enable more advanced analysis features), please see [all the settings for `gopls`](https://github.com/golang/vscode-go/blob/master/docs/settings.md#settings-for-gopls).
+`gopls` uses the `go` command to analyze your code. The extension automatically propagates necessary settings such as `"go.buildFlags"`, `"go.buildTags"`, `"go.toolsEnvVars"` and the path to the right `go` command to `gopls`. No extra settings should be necessary, but when you need to adjust `gopls`'s behavior further (e.g., enable more advanced analysis features), please see [all the settings for `gopls`](settings.md#settings-for-gopls).
If you encounter issues with `gopls`, please read the [troubleshooting guide](troubleshooting.md#collect-gopls-information). If you want to run the extension without the language server, you can disable it by setting `"go.useLanguageServer": false`.
