Previously we recomended rerunning another import for maven workspace…

…s, which would not help. Now we include a link to the new documentation page about maven. We also added additional gradle and mill documentation.

docs/build-tools/gradle.md

@@ -0,0 +1,97 @@
+---
+id: gradle
+title: Gradle
+---
+
+Gradle is a build tool that can be used easily with a large number of
+programming languages including Scala. Using it you can easily define your
+builds using Groovy or Kotlin, which enables for a high degree of customization.
+You can look up all the possible features on the
+[Gradle website](https://gradle.org/).
+
+## Automatic installation
+
+The first time you open Metals in a new workspace it prompts you to import the
+build. Select "Import build" to start automatic installation. After it's
+finished you should be able edit and compile your code.
+
+## Manual installation
+
+In a highly customized workspaces it might not be possible to use automatic
+import. In such cases there is a number of steps required to generate the needed
+Bloop config.
+
+First we need to add the Bloop plugin dependency to the project, it should be
+included in the buildscript section:
+
+```groovy
+buildscript {
+    repositories {
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'ch.epfl.scala:gradle-bloop_2.11:@@BLOOP_VERSION@@'
+    }
+}
+```
+
+Secondly, we need to enable the plugin for all the projects we want to include,
+it's easiest to define it for `allprojects`:
+
+```groovy
+allprojects {
+   apply plugin: bloop.integrations.gradle.BloopPlugin
+}
+```
+
+Now we can run `gradle bloopInstall`, which will create a Bloop configuration
+files. This will enable us to work with Metals and most features will work, but
+for everything to work properly we need to also add the SemanticDB plugin. This
+can be done by adding a couple of options to the scala compiler:
+
+```groovy
+allprojects {
+    afterEvaluate {
+        configurations {
+            scalaCompilerPlugin
+        }
+        dependencies {
+            scalaCompilerPlugin "org.scalameta:semanticdb-scalac_$scalaVersion:@@SCALAMETA_VERSION@@"
+        }
+        def pluginFile = project.configurations.scalaCompilerPlugin.find {
+            it.name.contains("semanticdb")
+        }
+        if (!pluginFile) {
+            throw new RuntimeException("SemanticDB plugin not found!")
+        }
+        tasks.withType(ScalaCompile) {
+            def params = [
+                '-Xplugin:' + pluginFile.absolutePath,
+                '-P:semanticdb:synthetics:on',
+                '-P:semanticdb:failures:warning',
+                '-P:semanticdb:sourceroot:' + project.rootProject.projectDir,
+                '-Yrangepos',
+                '-Xplugin-require:semanticdb'
+            ]
+            if (scalaCompileOptions.additionalParameters)
+                scalaCompileOptions.additionalParameters += params
+            else
+                scalaCompileOptions.additionalParameters = params
+        }
+    }
+}
+```
+
+You need to also define `scalaVersion` which corresponds to the scala version in
+your project. We also use afterEvaluate here so that we have scala dependency
+and all build specific scala compiler options defined before adding the
+SemanticDB plugin. It might be not needed in your project depending on the
+specifics.
+
+Now you can rerun `gradle bloopInstall` to have a properly configured SemanticDB
+plugin in Bloop config.
+
+This is much more complex than in case of the automatic installation, so it is
+recommended to only do manual installation in case of problems with the
+automatic one. You can also always try to reach us on the Metals gitter channel
+in case of any problems.

docs/build-tools/maven.md

@@ -0,0 +1,74 @@
+---
+id: maven
+title: Maven
+---
+
+Maven is one of the most common build tools in the JVM ecosystem and it also
+allows for using scala through the
+[scala-maven-plugin](https://davidb.github.io/scala-maven-plugin/usage.html).
+The [scalor-maven-plugin](https://github.com/random-maven/scalor-maven-plugin)
+is not supported, see \$LINK for more information.
+
+## Automatic installation
+
+The first time you open Metals in a new workspace it prompts you to import the
+build. Select "Import build" to start automatic installation.
+
+This will create all the needed Bloop files, however there will be a warning,
+since the SemanticDB plugin was not added yet in the automatic import. This will
+be added later. Most features should work without it, however some require
+SemanticDB files to be provided alongside compiled data. To do that we need a
+couple of steps that are explained in the manual installation section.
+
+## Manual instalation
+
+First, we need to add a couple of options to the Scala compiler in the
+configuration section:
+
+```xml
+<plugin>
+<groupId>net.alchim31.maven</groupId>
+<artifactId>scala-maven-plugin</artifactId>
+<version>4.0.2</version>
+...
+<configuration>
+    <compilerPlugins>
+        <compilerPlugin>
+            <groupId>org.scalameta</groupId>
+            <artifactId>semanticdb-scalac_${scala.version}</artifactId>
+            <version>@@SCALAMETA_VERSION@@</version>
+        </compilerPlugin>
+    </compilerPlugins>
+    <args>
+        <arg>-P:semanticdb:synthetics:on</arg>
+        <arg>-P:semanticdb:failures:warning</arg>
+        <arg>-P:semanticdb:sourceroot:${maven.multiModuleProjectDirectory}</arg>
+        <arg>-Yrangepos</arg>
+        <arg>-Xplugin-require:semanticdb</arg>
+    </args>
+</configuration>
+...
+</plugin>
+```
+
+Next, we need to do run bloopInstall via maven, which can be done easily
+through:
+
+`mvn ch.epfl.scala:maven-bloop_2.10:@@BLOOP_VERSION@@:bloopInstall -DdownloadSources=true`
+
+Everything should now be correctly configured and work even when reimporting the
+project.
+
+If you don't want to modify the `pom.xml` you can also run bloopInstall with an
+additional parameter:
+
+```
+mvn ch.epfl.scala:maven-bloop_2.10:@@BLOOP_VERSION@@:bloopInstall -DdownloadSources=true -DaddScalacArgs=-Xplugin:/path/to/semanticdb-scalac.jar|-P:semanticdb:synthetics:on|-P:semanticdb:failures:warning|-P:semanticdb:sourceroot:/path/to/workspace|-Yrangepos|-Xplugin-require:semanticdb'
+```
+
+`-DaddScalacArgs` takes a string with additional scalac options separated by
+`|`. You would need to download the correct plugin first and manually replace
+`/path/to/semanticdb-scalac.jar` with the path to the semanticDB plugin jar.
+
+If you choose this option though you should select "Don't show again" when
+Metals prompts to import the build.

docs/build-tools/mill.md

@@ -0,0 +1,34 @@
+---
+id: mill
+title: Mill
+---
+
+Mill is one of the newest build tools developed by Li Haoyi in order to create
+something simpler and more intuitive than most of other today's build tools.
+There is an extensive documentation on the
+[Mill website](http://www.lihaoyi.com/mill/).
+
+## Automatic installation
+
+The first time you open Metals in a new workspace it prompts you to import the
+build. Select "Import build" to start automatic installation. After it's
+finished you should be able edit and compile your code.
+
+## Manual installation
+
+Manual instalation is not recommended, but it's pretty easy to do. There are
+only two steps involved.
+
+First add one import line to your `build.sc` file or in any other file it
+depends on:
+
+`` import $ivy.`com.lihaoyi::mill-contrib-bloop:VERSION` ``
+
+Remember to replace the `VERSION` with your mill version.
+
+After adding the line you should be able to generate Bloop config files needed
+to work with Metals using the below command:
+
+`mill mill.contrib.Bloop/install`
+
+Afterwards just can just open Metals and start working on your code.

docs/build-tools/overview.md

@@ -7,13 +7,14 @@ sidebar_label: Overview
 Metals works with the following build tools with varying degree of
 functionality.
 
-| Build tool | Installation | Goto library dependencies |
-| ---------- | :----------: | :-----------------------: |
-| sbt        |  Automatic   |            ✅             |
-| Bloop      |  Automatic   |  If configured correctly  |
-| Maven      |    Manual    |                           |
-| Gradle     |    Manual    |                           |
-| Mill       |    Manual    |                           |
+| Build tool | Installation | Goto library dependencies | Find references      |
+| ---------- | :----------: | :-----------------------: | :------------------: |
+| sbt        |  Automatic   |      Automatic            |     Automatic        |
+| Bloop      |  Automatic   |    Semi-automatic         |   Semi-automatic     |
+| Maven      |  Automatic   |      Automatic            |   Semi-automatic     |
+| Gradle     |  Automatic   |      Automatic            |     Automatic        |
+| Mill       |  Automatic   |      Automatic            |     Automatic        |
+
 
 ## Installation
 
@@ -31,14 +32,20 @@ compiler plugin and `-Yrangepos` option enabled.
 
 ## Goto library dependencies
 
-**✅**: it is possible to navigate Scala+Java library dependencies using "Goto
+**Automatic**: it is possible to navigate Scala+Java library dependencies using "Goto
 definition".
 
-**If configured correctly**: navigation in library dependency sources works as
+**Semi-automatic**: navigation in library dependency sources works as
 long as the
 [Bloop JSON files](https://scalacenter.github.io/bloop/docs/configuration-format/)
 are populated with `*-sources.jar`.
 
+## Find references
+
+**Automatic**: it is possible to find all references to a symbol in the project
+
+**Semi-automatic**: it is possible to find references as soon as we configure additional SemanticDB plugin for the compiler, check separate build tool pages for details
+
 ## Integrating a new build tool
 
 Metals works with any build tool that supports the

metals/src/main/scala/scala/meta/internal/metals/Doctor.scala

@@ -108,12 +108,19 @@ final class Doctor(
       isSemanticdbEnabled: Boolean,
       scala: ScalaTarget
   ): String = {
+
+    def isMaven: Boolean = workspace.resolve("pom.xml").isFile
+    def hint() =
+      if (isMaven)
+        "enable SemanticDB following instructions on the " +
+          "<a href=https://scalameta.org/metals/docs/build-tools/maven.html>Metals website</a>"
+      else s"run 'Build import' to enable code navigation."
+
     if (!isSemanticdbEnabled) {
       if (isSupportedScalaVersion(scalaVersion)) {
-        s"Run 'Build import' to enable code navigation."
+        hint().capitalize
       } else if (isSupportedScalaBinaryVersion(scalaVersion)) {
-        s"Upgrade to Scala ${recommendedVersion(scalaVersion)} and " +
-          s"run 'Build import' to enable code navigation."
+        s"Upgrade to Scala ${recommendedVersion(scalaVersion)} and " + hint()
       } else {
         s"Code navigation is not supported for this compiler version, upgrade to " +
           s"Scala ${BuildInfo.scala212} or ${BuildInfo.scala211} and " +
@@ -262,7 +269,7 @@ final class Doctor(
           .element("td", center)(_.text(completions))
           .element("td", center)(_.text(references))
           .element("td")(
-            _.text(recommendation(scalaVersion, isSemanticdbEnabled, target))
+            _.raw(recommendation(scalaVersion, isSemanticdbEnabled, target))
           )
       )
     }