Add index troubleshooting steps (#2633)

* Add index troubleshooting steps

* Apply suggestions from code review

Co-authored-by: Vinicius Stock <vinistock@users.noreply.github.com>

* Add link to error message

* Update test

* Fix linting

---------

Co-authored-by: Vinicius Stock <vinistock@users.noreply.github.com>

Author: Andy Waite

jekyll/troubleshooting.markdown

@@ -141,7 +141,7 @@ For example, if you configure `BUNDLE_PATH` to point to `vendor/bundle` so that
 directory as your project, `bundle install` will automatically pick that up and install them in the right place. But
 `gem install` will not as it requires a different setting to achieve it.
 
-You can apply your prefered installed locations for RubyGems by using the `~/.gemrc` file. In that file, you can decide
+You can apply your preferred installed locations for RubyGems by using the `~/.gemrc` file. In that file, you can decide
 to either install it with `--user-install` or select a specific installation directory with `--install-dir`.
 
 ```yaml
@@ -230,6 +230,18 @@ ruby-lsp
 Is there any extra information given from booting the server manually? Or does it only fail when booting through the
 extension?
 
+## Indexing
+
+When Ruby LSP starts, it attempts to index your code as well as your dependencies as described in [Configuring code indexing](index#configuring-code-indexing).
+
+In rare cases, Ruby LSP will encounter an error which prevents indexing from completing, which will result in incomplete information in the editor.
+
+Firstly, ensure that you are using the latest release of the `ruby-lsp` gem, as the problem may have been already fixed.
+
+To diagnose the particular file(s) causing a problem, run `ruby-lsp-check`. Please log an issue so that we can address it. If the code is not open source then please provide a minimal reproduction.
+
+In the meantime, you can [configure Ruby LSP to ignore a particular gem or file for indexing](index#configuring-code-indexing).
+
 ## After troubleshooting
 
 If after troubleshooting the Ruby LSP is still not initializing properly, please report an issue

lib/ruby_lsp/server.rb

@@ -969,7 +969,9 @@ def perform_initial_indexing
             false
           end
         rescue StandardError => error
-          send_message(Notification.window_show_error("Error while indexing: #{error.message}"))
+          message = "Error while indexing (see [troubleshooting steps]" \
+            "(https://shopify.github.io/ruby-lsp/troubleshooting#indexing)): #{error.message}"
+          send_message(Notification.window_show_error(message))
         end
 
         # Indexing produces a high number of short lived object allocations. That might lead to some fragmentation and

test/server_test.rb

@@ -186,8 +186,10 @@ def test_initialized_recovers_from_indexing_failures
 
     notification = @server.pop_response
     assert_equal("window/showMessage", notification.method)
+    expected_message = "Error while indexing (see [troubleshooting steps]" \
+      "(https://shopify.github.io/ruby-lsp/troubleshooting#indexing)): boom!"
     assert_equal(
-      "Error while indexing: boom!",
+      expected_message,
       T.cast(notification.params, RubyLsp::Interface::ShowMessageParams).message,
     )
   end