Docs: restore docs from Sourcegraph.com (#366)

Author: chrismwendt

README.md

@@ -100,6 +100,89 @@ interface GoInitializationOptions {
 }
 ```
 
+## Debugging Go code intelligence
+
+Additional configuration for Go code intelligence may be required in some cases:
+
+- [Custom GOPATHs / Go monorepos](#custom-gopaths--go-monorepos)
+- [Vanity import paths](#vanity-import-paths)
+
+### Custom GOPATHs / Go monorepos
+
+By default, Sourcegraph assumes that Go code in a repository represents Go packages that would be placed under `$GOPATH/src/...`. That
+is, a Go repository is assumed to only contain Go packages.
+
+For some repositories, such as Go monorepos, this may not be the case. These repositories typically have an entire (or multiple) `$GOPA
+TH` directories comitted to them, and the Go language server may not be able to provide code intelligence without being informed of thi
+s.
+
+To inform Sourcegraph's Go language server that your repository contains an entire `$GOPATH` directory, you can use one of three option
+s:
+
+1.  **Auto-detection via `.vscode/settings.json`**
+
+    Sourcegraph will automatically detect a Visual Studio Code `settings.json` file with a GOPATH configuration. You may already have o
+ne of these files if you are using Visual Studio Code with the Go extension. The file `.vscode/settings.json` would look like:
+
+    ```json
+    {
+      "go.gopath": "${workspaceRoot}/YOUR_GOPATH"
+    }
+    ```
+
+    In this case, Sourcegraph would look for a folder named `YOUR_GOPATH` in the root of the repository.
+
+2.  **Auto-detection via `.envrc`**
+
+    Sourcegraph will also automatically detect a GOPATH from an `.envrc` file in the root of the repository. You may already have one of these if you are using direnv. For example a file such as:
+
+    ```bash
+    export GOPATH=${PWD}/third_party
+    GOPATH_add code:code2
+    GOPATH_add /absolute
+    ```
+
+    Would lead to Sourcegraph using a final `GOPATH` of `third_party:code:code2`. Note that we will ignore any `/absolute` path, and that we do not execute `.envrc` files but rather scan them for simple syntax such as the above. If you use a more complex `.envrc` file to build your `GOPATH`, this auto-detection may not work for you.
+
+3.  **Manual configuration via `.sourcegraph/config.json`**
+
+    If you add a `.sourcegraph/config.json` file in the root directory of your repository, Sourcegraph will use this configuration to determine the `GOPATH` instead of the auto-detection methods described above. An example configuration is:
+
+    ```json
+    {
+      "go": {
+        "GOPATH": ["/third_party", "code"]
+      }
+    }
+    ```
+
+    Sourcegraph will use a final `GOPATH` of `third_party:code`. That is, it will assume the `third_party` and `code` directories in the root of the repository are to be used as `$GOPATH` directories.
+
+### Vanity import paths
+
+When the Go language server encounters a vanity import path, it must be able to locate the source code for it or else code intelligence will not work for code related to that dependency.
+
+For example, consider a repository `github.com/example/server` which contains Go code with an `import "example.io/pkg/logger"` statement.
+
+1.  If the source code for `example.io/pkg/logger` is located under a vendor directory, Sourcegraph will use that in the same manner that the `go` tool would.
+2.  If the source code for `example.io/pkg/logger` is inside of the current repository at e.g. `github.com/example/pkg/logger`, Sourcegraph will look for it by scanning the repository for a [canonical import path comment](https://golang.org/doc/go1.4#canonicalimports) using some heuristics.
+
+    - For example, if Sourcegraph finds a canonical import path comment such as `package logger // import "example.io/pkg/logger"` in the `pkg/logger` directory of the repository, Sourcegraph will assume that the code in the `pkg/logger` directory is what should be used when a `import "example.io/pkg/logger"` statement is seen.
+    - Note that Sourcegraph only needs to find one such comment for the `example.io` domain in order to resolve all other vanity imports. That is, placing this comment in `pkg/logger/logger.go` is enough for Sourcegraph to know how to import any package under `example.io/...`.
+    - Sometimes the Go language server's heuristics are not able to locate a canonical import path comment in a repository, in which case you can specify the root import path of your repository directly by placing a `.sourcegraph/config.json` file in the root of your repository, e.g.:
+
+    ```json
+    {
+      "go": {
+        "RootImportPath": "example.io/pkg"
+      }
+    }
+    ```
+
+    Which would tell the Go language server to clone `github.com/example/pkg` into `$GOPATH/src/example.io/pkg`.
+
+3.  Otherwise, Sourcegraph will attempt to fetch `example.io/pkg/logger` via the network using `go get example.io/pkg/logger`.
+
 ## Profiling
 
 If you run into performance issues while using the language server, it can be very helpful to attach a CPU or memory profile with the issue report. To capture one, first [install Go](https://golang.org/doc/install), start `go-langserver` with the pprof flag (e.g. `$GOPATH/bin/go-langserver -pprof :6060`) and then:

buildserver/environment.go

@@ -278,7 +278,7 @@ type sourcegraphConfig struct {
 		// This is to support monorepos such as the ones described in
 		// https://blog.gopheracademy.com/advent-2015/go-in-a-monorepo/
 		//
-		// See https://docs.sourcegraph.com/extensions/language_servers/go#custom-gopaths-go-monorepos.
+		// See https://github.com/sourcegraph/go-langserver#custom-gopaths-go-monorepos.
 		GOPATH []string
 
 		// RootImportPath defines what Go import path corresponds to the
@@ -289,7 +289,7 @@ type sourcegraphConfig struct {
 		// information (from glide.yml or canonical import path comments) and
 		// gives you an opportunity to specify it directly.
 		//
-		// See https://docs.sourcegraph.com/extensions/language_servers/go#vanity-import-paths.
+		// See https://github.com/sourcegraph/go-langserver#vanity-import-paths.
 		RootImportPath string
 	} `json:"go"`
 }