coc-solargraph

coc-solargraph

Ruby language server extension using solargraph for coc.nvim.

Note: remember use fnameescape() for solargraph uri (solargraph:/) to open it by vim command.

Note: solargraph scheme returns html, but vim doesn't handle html, so it's converted to markdown.

Install

Install solargraph by:

gem install solargraph

In your vim/neovim, run command:

:CocInstall coc-solargraph

Features

Coc.nvim support all features of solargraph

Transport Options

Extension version 1.0.0 introduces the solargraph.transport setting with the following options:

• socket: Run a TCP server. This is the default option.
• stdio: Run a STDIO server.
• external: Connect to an external server instead of starting a new one.

Most users should use the default socket option or switch to stdio in case of network issues.

The external option is intended for cases where the project is hosted in a different environment from the editor, such as a docker container or a remote server. Users can opt to run a socket server in the remote environment and connect to it via TCP. The extension waits for the socket's connect event before handing the connection to the language client. If the connection fails, Coc prompts you to try again. Example configuration:

"solargraph.transport": "external",
"solargraph.externalServer": {
    "host": "localhost",
    "port": 7658
}

The port can also be provided as a string when the configuration is generated or supplied by another tool:

"solargraph.externalServer": {
    "host": "localhost",
    "port": "7658"
}

Documenting Your Code

Using YARD for inline documentation is highly recommended. Solargraph will use YARD comments to provide the best code completion and API reference it can.

In addition to the standard YARD tags, Solargraph defines a @type tag for documenting variable types. It works with both local and instance variables. Example:

# @type [String]
my_variable = some_method_call
my_variable. # <= Hitting crtl-space here will suggest String instance methods

Gem Support

Solargraph is capable of providing code completion and documentation for gems. When your code uses require to include a gem, its classes and methods become available in completion and intellisense.

You can make sure your gems are available with the commands Build new gem documentation or Rebuild all gem documentation in the :CocCommand list.

Solargraph and Bundler

If your project uses Bundler, the most comprehensive way to use your bundled gems is to bundle Solargraph.

In the Gemfile:

gem 'solargraph', group: :development

Run bundle install and use bundle exec yard gems to generate the documentation. This process documents cached or vendored gems, or even gems that are installed from a local path.

In order to access intellisense for bundled gems, you'll need to start the language server with Bundler by setting the solargraph.useBundler option to true.

Diagnostics (Linting)

To enable diagnostics, set the solargraph.diagnostics configuration to true.

Solargraph uses RuboCop for diagnostics by default. If your project has a .solargraph.yml file, you can configure the diagnostics in its reporters section. Example:

reporters:
- rubocop

See Solargraph Tips for more information about the .solargraph.yml file.

Use a .rubocop.yml file in your project's root folder to customize the linting rules.

Restarting Solargraph

Some changes you make to a project, such as updating the Gemfile, might require you to restart the Solargraph server. Run the following command to restart only the Solargraph language server:

:CocCommand solargraph.restart

The restart command disposes of the current language client and starts a new one using the current configuration. The server can request the same lifecycle operation by sending the $/solargraph/restart notification; this notification triggers a silent client restart without showing a duplicate user message.

Documentation pages opened through commands such as solargraph.search and solargraph.environment continue to use Coc's existing solargraph text document content provider. Cached documentation remains associated with that provider when the language client is restarted.

Updating the Core Documentation

The Solargraph gem ships with documentation for Ruby 2.2.2. As of gem version 0.15.0, there's an option to download additional documentation for other Ruby versions from the command line.

$ solargraph list-cores      # List the installed documentation versions
$ solargraph available-cores # List the versions available for download
$ solargraph download-core   # Install the best match for your Ruby version
$ solargraph clear-cores     # Clear the documentation cache

License

MIT