Solargraph

A Ruby Language Server

Tips for Using Solargraph

Here are some recommendations for getting the most out of Solargraph. The sample screenshots are taken from Visual Studio Code.

Writing Documentation

Detecting the return type of a method

Solargraph integrates with YARD to provide rich documentation for classes, modules, and methods. The following example code demonstrates some of the basic features:


# The Foo class
#
class Foo
  # The bar method
  #
  # @return [String]
  def bar
  end
end
		

The descriptions for the Foo class and the bar method will appear in VS Code's quick info window for their respective completion suggestions.

The @return tag in the bar method's documentation is especially useful. Solargraph uses it to provide String method suggestions when you chain methods, e.g., Foo.new.bar.

There are many other YARD tags that Solargraph can use to improve suggestions, such as @param and @yieldparam. See the YARD tag documentation for more information.

Detecting and Documenting Variable Types

Solargraph can automatically detect variables' types from their assignments. Any of the following is detectable:

  • Literal values (strings, numbers, arrays, and hashes)
  • Objects created with #new, e.g., Hash.new
  • Any method call with a documented return type

Types will be automatically detected for all of the following:


var1 = "hello"        #=> String
var2 = var1.join(',') #=> Array
var3 = Foo.new        #=> Foo (given the above Foo class)
var4 = var3.bar       #=> String (given the above Foo class)
		

Solargraph also adds a special @type tag for documenting variables. Put it directly above a variable assignment to specify its type. It works with local variables, instance variables, class variables, and constants. Example:


# @type [String]
my_string = a_method_that_returns_a_string
		

Documenting Gems

Solargraph can provide completion and other features for gems that have YARD documentation. To document your gems, run `yard gems` from the command line.

The VS Code extension provides shortcuts for generating the documentation from the command palette.

Configuring Projects

The Solargraph server looks for a .solargraph.yml at the root of a project for configuration settings. In the VS Code extension, for example, the .solargraph.yml should be in the root folder.

Create a Default Configuration

Go to the project root and run solargraph config.


$ cd /path/to/project
$ solargraph config
		

Configuration Options

The default configuration looks something like this:


---
include:
- "**/*.rb"
exclude:
- spec/**/*
- test/**/*
- vendor/**/*
require: []
reporters: []
domains: []
plugins: []
max_files: 5000
		

include

A list of directory globs to include in Solargraph's code maps. The default configuration includes all .rb files in the folder.

exclude

A list of directory globs to exclude from Solargraph's code maps. The default configuration excludes the spec, test, and vendor folders.

require

Use require to add require paths that are not explicitly defined in code.

Example:

require:
- sinatra/base
		

Solargraph will act as if a file in the project contained the line require 'sintatra/base'.

reporters

Use reporters to configure diagnostics. Current valid reporters are rubocop and require_not_found.

rubocop provides RuboCop linting. If your project has a .rubocop.yml file, Solargraph will use it to configure the linting rules.

require_not_found reports required paths that could not be resolved to either a project file or a gem.

domains

Solargraph will use the designated classes and modules as contexts in which the project's scripts will run. Example: if one of the domains is Class<Sinatra::Base>, the Sinatra DSL will be included in suggestions. (Whether you need to specify the domain inside Class<> depends on how the library is implemented.)

plugins

A list of plugins to enhance suggestions. The experimental runtime plugin is included in Solargraph, but disabled by default; you need to add it to the plugins list to activate it:


plugins:
- runtime
		

Warning: The runtime plugin is highly experimental and prone to bugs.

max_files

The maximum number of files to be mapped in the workspace. If the workspace exceeds the maximum, the language server will still map individual files opened in the client. The limit can be removed altogether by settings max_files to 0.