diff --git a/.github/workflows/publish_docs.yml b/.github/workflows/publish_docs.yml index 7f55c7675..902fa7ae0 100644 --- a/.github/workflows/publish_docs.yml +++ b/.github/workflows/publish_docs.yml @@ -23,13 +23,10 @@ jobs: git config user.email github-actions@github.com - name: Generate documentation - run: bundle exec rake rdoc - - - name: Copy README images to the docs folder + working-directory: ./jekyll run: | - mkdir docs/vscode - cp vscode/icon.png docs/vscode/icon.png - cp -R vscode/extras docs/vscode/ + bundle install + bundle exec jekyll build - name: Commit to gh-pages run: | diff --git a/.rubocop.yml b/.rubocop.yml index 36a502e57..6575a465f 100644 --- a/.rubocop.yml +++ b/.rubocop.yml @@ -20,6 +20,7 @@ AllCops: - "features/**/*" - "test/fixtures/**/*" - "test/expectations/**/*" + - "jekyll/**/*" Minitest/AssertPredicate: Enabled: true diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4a77640bb..f48802adc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,15 @@ # CONTRIBUTING +## Contributing to documentation + +Ruby LSP uses [Jekyll](https://jekyllrb.com/) to generate the documentation, which's source lives under the `/jekyll` folder. + +```shell +cd jekyll +bundle install +bundle exec jekyll serve # Builds the site and serves it at http://localhost:4000/ruby-lsp +``` + ## Testing changes ### Tracing LSP requests and responses diff --git a/README.md b/README.md index 6283b6eb0..1f8d6ad60 100644 --- a/README.md +++ b/README.md @@ -15,119 +15,9 @@ experience to Ruby developers using modern standards for cross-editor features, Want to discuss Ruby developer experience? Consider joining the public [Ruby DX Slack workspace](https://join.slack.com/t/ruby-dx/shared_invite/zt-2c8zjlir6-uUDJl8oIwcen_FS_aA~b6Q). -## Features +## Getting Started -![Ruby LSP demo](vscode/extras/ruby_lsp_demo.gif) - -The Ruby LSP features include - -- Semantic highlighting -- Symbol search and code outline -- RuboCop errors and warnings (diagnostics) -- Format on save (with RuboCop or Syntax Tree) -- Format on type -- Debugging support -- Running and debugging tests through VS Code's UI -- Go to definition for classes, modules, constants and required files -- Showing documentation on hover for classes, modules and constants -- Completion for classes, modules, constants and require paths -- Fuzzy search classes, modules and constants anywhere in the project and its dependencies (workspace symbol) - -As of July 2024, Ruby LSP has received significant enhancements to its code navigation features. For an in-depth look at these improvements, including video demonstrations, check out this [article](https://railsatscale.com/2024-07-18-mastering-ruby-code-navigation-major-enhancements-in-ruby-lsp-2024/). Despite these advancements, we plan to continue enhancing its code navigation support even further. You can follow our progress on this [GitHub issue](https://github.com/Shopify/ruby-lsp/issues/899). - -See complete information about features [here](https://shopify.github.io/ruby-lsp/RubyLsp/Requests.html). - -If you experience issues, please see the [troubleshooting -guide](https://github.com/Shopify/ruby-lsp/blob/main/TROUBLESHOOTING.md). - -## Usage - -### With VS Code - -If using VS Code, all you have to do is install the [Ruby LSP -extension](https://marketplace.visualstudio.com/items?itemName=Shopify.ruby-lsp) to get the extra features in the -editor. Do not install the `ruby-lsp` gem manually. - -For more information on using and configuring the extension, see [vscode/README.md](vscode/README.md). - -### With other editors - -See [editors](EDITORS.md) for community instructions on setting up the Ruby LSP, which current includes Emacs, Neovim, Sublime Text, and Zed. - -The gem can be installed by doing -```shell -gem install ruby-lsp -``` - -and the language server can be launched running `ruby-lsp` (without bundle exec in order to properly hook into your -project's dependencies). - -### Documentation - -See the [documentation](https://shopify.github.io/ruby-lsp) for more in-depth details about the -[supported features](https://shopify.github.io/ruby-lsp/RubyLsp/Requests.html). - -For creating rich themes for Ruby using the semantic highlighting information, see the [semantic highlighting -documentation](SEMANTIC_HIGHLIGHTING.md). - -### Configuring code indexing - -By default, the Ruby LSP indexes all Ruby files defined in the current project and all of its dependencies, including -default gems, except for - -- Gems that only appear under the `:development` group -- All Ruby files under `test/**/*.rb` - -This behaviour can be overridden and tuned. Learn how to configure it [for VS Code](vscode/README.md#Indexing-Configuration) or [for other editors](EDITORS.md#Indexing-Configuration). - -Note that indexing-dependent behavior, such as definition, hover, completion or workspace symbol will be impacted by -the configuration changes. - -The older approach of using a `.index.yml` file has been deprecated and will be removed in a future release. - -```yaml -# Exclude files based on a given pattern. Often used to exclude test files or fixtures -excluded_patterns: - - "**/spec/**/*.rb" - -# Include files based on a given pattern. Can be used to index Ruby files that use different extensions -included_patterns: - - "**/bin/*" - -# Exclude gems by name. If a gem is never referenced in the project's code and is only used as a tool, excluding it will -# speed up indexing and reduce the amount of results in features like definition or completion -excluded_gems: - - rubocop - - pathname - -# Include gems by name. Normally used to include development gems that are excluded by default -included_gems: - - prism -``` - -### Addons - -The Ruby LSP provides an addon system that allows other gems to enhance the base functionality with more editor -features. This is the mechanism that powers addons like - -- [Ruby LSP Rails](https://github.com/Shopify/ruby-lsp-rails) -- [Ruby LSP RSpec](https://github.com/st0012/ruby-lsp-rspec) -- [Ruby LSP rubyfmt](https://github.com/jscharf/ruby-lsp-rubyfmt) - -Additionally, some tools may include a Ruby LSP addon directly, like - -- [Standard Ruby (from v1.39.1)](https://github.com/standardrb/standard/wiki/IDE:-vscode#using-ruby-lsp) - -Other community driven addons can be found in [rubygems](https://rubygems.org/search?query=name%3A+ruby-lsp) by -searching for the `ruby-lsp` prefix. - -For instructions on how to create addons, see the [addons documentation](ADDONS.md). - -## Learn More - -* [RubyConf 2022: Improving the development experience with language servers](https://www.youtube.com/watch?v=kEfXPTm1aCI) ([Vinicius Stock](https://github.com/vinistock)) -* [Remote Ruby: Ruby Language Server with Vinicius Stock](https://remoteruby.com/221) -* [RubyKaigi 2023: Code indexing - How language servers understand our code](https://www.youtube.com/watch?v=ks3tQojSJLU) ([Vinicius Stock](https://github.com/vinistock)) +Please refer to the official [documentation](https://shopify.github.io/ruby-lsp) for more information about [installation and usage](https://shopify.github.io/ruby-lsp#usage) and [supported features](https://shopify.github.io/ruby-lsp#features). ## Contributing diff --git a/jekyll/.gitignore b/jekyll/.gitignore new file mode 100644 index 000000000..f40fbd8ba --- /dev/null +++ b/jekyll/.gitignore @@ -0,0 +1,5 @@ +_site +.sass-cache +.jekyll-cache +.jekyll-metadata +vendor diff --git a/jekyll/404.html b/jekyll/404.html new file mode 100644 index 000000000..086a5c9ea --- /dev/null +++ b/jekyll/404.html @@ -0,0 +1,25 @@ +--- +permalink: /404.html +layout: default +--- + + + +
+

404

+ +

Page not found :(

+

The requested page could not be found.

+
diff --git a/jekyll/Gemfile b/jekyll/Gemfile new file mode 100644 index 000000000..7723636ea --- /dev/null +++ b/jekyll/Gemfile @@ -0,0 +1,37 @@ +# frozen_string_literal: true + +source "https://rubygems.org" +# Hello! This is where you manage which Jekyll version is used to run. +# When you want to use a different version, change it below, save the +# file and run `bundle install`. Run Jekyll with `bundle exec`, like so: +# +# bundle exec jekyll serve +# +# This will help ensure the proper Jekyll version is running. +# Happy Jekylling! +gem "jekyll", "~> 4.3.3" + +# Theme +gem "just-the-docs", "~> 0.10.0" + +# If you want to use GitHub Pages, remove the "gem "jekyll"" above and +# uncomment the line below. To upgrade, run `bundle update github-pages`. +# gem "github-pages", group: :jekyll_plugins +# If you have any plugins, put them here! +group :jekyll_plugins do + gem "jekyll-feed", "~> 0.12" +end + +# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem +# and associated library. +platforms :mingw, :x64_mingw, :mswin, :jruby do + gem "tzinfo", ">= 1", "< 3" + gem "tzinfo-data" +end + +# Performance-booster for watching directories on Windows +gem "wdm", "~> 0.1.1", platforms: [:mingw, :x64_mingw, :mswin] + +# Lock `http_parser.rb` gem to `v0.6.x` on JRuby builds since newer versions of the gem +# do not have a Java counterpart. +gem "http_parser.rb", "~> 0.6.0", platforms: [:jruby] diff --git a/jekyll/Gemfile.lock b/jekyll/Gemfile.lock new file mode 100644 index 000000000..634ebdfe6 --- /dev/null +++ b/jekyll/Gemfile.lock @@ -0,0 +1,185 @@ +GEM + remote: https://rubygems.org/ + specs: + addressable (2.8.7) + public_suffix (>= 2.0.2, < 7.0) + bigdecimal (3.1.8) + colorator (1.1.0) + concurrent-ruby (1.3.4) + em-websocket (0.5.3) + eventmachine (>= 0.12.9) + http_parser.rb (~> 0) + eventmachine (1.2.7) + ffi (1.17.0) + ffi (1.17.0-aarch64-linux-gnu) + ffi (1.17.0-aarch64-linux-musl) + ffi (1.17.0-arm-linux-gnu) + ffi (1.17.0-arm-linux-musl) + ffi (1.17.0-arm64-darwin) + ffi (1.17.0-x86-linux-gnu) + ffi (1.17.0-x86-linux-musl) + ffi (1.17.0-x86_64-darwin) + ffi (1.17.0-x86_64-linux-gnu) + ffi (1.17.0-x86_64-linux-musl) + forwardable-extended (2.6.0) + google-protobuf (4.28.0) + bigdecimal + rake (>= 13) + google-protobuf (4.28.0-aarch64-linux) + bigdecimal + rake (>= 13) + google-protobuf (4.28.0-arm64-darwin) + bigdecimal + rake (>= 13) + google-protobuf (4.28.0-x86-linux) + bigdecimal + rake (>= 13) + google-protobuf (4.28.0-x86_64-darwin) + bigdecimal + rake (>= 13) + google-protobuf (4.28.0-x86_64-linux) + bigdecimal + rake (>= 13) + http_parser.rb (0.8.0) + i18n (1.14.5) + concurrent-ruby (~> 1.0) + jekyll (4.3.3) + addressable (~> 2.4) + colorator (~> 1.0) + em-websocket (~> 0.5) + i18n (~> 1.0) + jekyll-sass-converter (>= 2.0, < 4.0) + jekyll-watch (~> 2.0) + kramdown (~> 2.3, >= 2.3.1) + kramdown-parser-gfm (~> 1.0) + liquid (~> 4.0) + mercenary (>= 0.3.6, < 0.5) + pathutil (~> 0.9) + rouge (>= 3.0, < 5.0) + safe_yaml (~> 1.0) + terminal-table (>= 1.8, < 4.0) + webrick (~> 1.7) + jekyll-feed (0.17.0) + jekyll (>= 3.7, < 5.0) + jekyll-include-cache (0.2.1) + jekyll (>= 3.7, < 5.0) + jekyll-sass-converter (3.0.0) + sass-embedded (~> 1.54) + jekyll-seo-tag (2.8.0) + jekyll (>= 3.8, < 5.0) + jekyll-watch (2.2.1) + listen (~> 3.0) + just-the-docs (0.10.0) + jekyll (>= 3.8.5) + jekyll-include-cache + jekyll-seo-tag (>= 2.0) + rake (>= 12.3.1) + kramdown (2.4.0) + rexml + kramdown-parser-gfm (1.1.0) + kramdown (~> 2.0) + liquid (4.0.4) + listen (3.9.0) + rb-fsevent (~> 0.10, >= 0.10.3) + rb-inotify (~> 0.9, >= 0.9.10) + mercenary (0.4.0) + pathutil (0.16.2) + forwardable-extended (~> 2.6) + public_suffix (6.0.1) + rake (13.2.1) + rb-fsevent (0.11.2) + rb-inotify (0.11.1) + ffi (~> 1.0) + rexml (3.3.7) + rouge (4.3.0) + safe_yaml (1.0.5) + sass-embedded (1.78.0) + google-protobuf (~> 4.27) + rake (>= 13) + sass-embedded (1.78.0-aarch64-linux-android) + google-protobuf (~> 4.27) + sass-embedded (1.78.0-aarch64-linux-gnu) + google-protobuf (~> 4.27) + sass-embedded (1.78.0-aarch64-linux-musl) + google-protobuf (~> 4.27) + sass-embedded (1.78.0-aarch64-mingw-ucrt) + google-protobuf (~> 4.27) + sass-embedded (1.78.0-arm-linux-androideabi) + google-protobuf (~> 4.27) + sass-embedded (1.78.0-arm-linux-gnueabihf) + google-protobuf (~> 4.27) + sass-embedded (1.78.0-arm-linux-musleabihf) + google-protobuf (~> 4.27) + sass-embedded (1.78.0-arm64-darwin) + google-protobuf (~> 4.27) + sass-embedded (1.78.0-riscv64-linux-android) + google-protobuf (~> 4.27) + sass-embedded (1.78.0-riscv64-linux-gnu) + google-protobuf (~> 4.27) + sass-embedded (1.78.0-riscv64-linux-musl) + google-protobuf (~> 4.27) + sass-embedded (1.78.0-x86-cygwin) + google-protobuf (~> 4.27) + sass-embedded (1.78.0-x86-linux-android) + google-protobuf (~> 4.27) + sass-embedded (1.78.0-x86-linux-gnu) + google-protobuf (~> 4.27) + sass-embedded (1.78.0-x86-linux-musl) + google-protobuf (~> 4.27) + sass-embedded (1.78.0-x86-mingw-ucrt) + google-protobuf (~> 4.27) + sass-embedded (1.78.0-x86_64-cygwin) + google-protobuf (~> 4.27) + sass-embedded (1.78.0-x86_64-darwin) + google-protobuf (~> 4.27) + sass-embedded (1.78.0-x86_64-linux-android) + google-protobuf (~> 4.27) + sass-embedded (1.78.0-x86_64-linux-gnu) + google-protobuf (~> 4.27) + sass-embedded (1.78.0-x86_64-linux-musl) + google-protobuf (~> 4.27) + terminal-table (3.0.2) + unicode-display_width (>= 1.1.1, < 3) + unicode-display_width (2.5.0) + webrick (1.8.1) + +PLATFORMS + aarch64-linux + aarch64-linux-android + aarch64-linux-gnu + aarch64-linux-musl + aarch64-mingw-ucrt + arm-linux-androideabi + arm-linux-gnu + arm-linux-gnueabihf + arm-linux-musl + arm-linux-musleabihf + arm64-darwin + riscv64-linux-android + riscv64-linux-gnu + riscv64-linux-musl + ruby + x86-cygwin + x86-linux + x86-linux-android + x86-linux-gnu + x86-linux-musl + x86-mingw-ucrt + x86_64-cygwin + x86_64-darwin + x86_64-linux + x86_64-linux-android + x86_64-linux-gnu + x86_64-linux-musl + +DEPENDENCIES + http_parser.rb (~> 0.6.0) + jekyll (~> 4.3.3) + jekyll-feed (~> 0.12) + just-the-docs (~> 0.10.0) + tzinfo (>= 1, < 3) + tzinfo-data + wdm (~> 0.1.1) + +BUNDLED WITH + 2.5.11 diff --git a/jekyll/_config.yml b/jekyll/_config.yml new file mode 100644 index 000000000..dd824d738 --- /dev/null +++ b/jekyll/_config.yml @@ -0,0 +1,63 @@ +# Welcome to Jekyll! +# +# This config file is meant for settings that affect your whole blog, values +# which you are expected to set up once and rarely edit after that. If you find +# yourself editing this file very often, consider using Jekyll's data files +# feature for the data you need to update frequently. +# +# For technical reasons, this file is *NOT* reloaded automatically when you use +# 'bundle exec jekyll serve'. If you change this file, please restart the server process. +# +# If you need help with YAML syntax, here are some quick references for you: +# https://learn-the-web.algonquindesign.ca/topics/markdown-yaml-cheat-sheet/#yaml +# https://learnxinyminutes.com/docs/yaml/ +# +# Site settings +# These are used to personalize your new site. If you look in the HTML files, +# you will see them accessed via {{ site.title }}, {{ site.email }}, and so on. +# You can create any custom variable you would like, and they will be accessible +# in the templates via {{ site.myvariable }}. + +title: Ruby LSP +description: >- # this means to ignore newlines until "baseurl:" + Write an awesome description for your new site here. You can edit this + line in _config.yml. It will appear in your document head meta (for + Google search results) and in your feed.xml site, e.g. /blog +baseurl: "/ruby-lsp" +url: "https://shopify.github.io" +github_username: shopify + +aux_links: + "Ruby LSP on GitHub": + - "https://github.com/Shopify/ruby-lsp" + "Ruby DX Slack": + - "https://join.slack.com/t/ruby-dx/shared_invite/zt-2c8zjlir6-uUDJl8oIwcen_FS_aA~b6Q" + +# Build settings +theme: just-the-docs +plugins: + - jekyll-feed + +layout: minimal + +destination: ../docs + +# Exclude from processing. +# The following items will not be processed, by default. +# Any item listed under the `exclude:` key here will be automatically added to +# the internal "default list". +# +# Excluded items can be processed by explicitly listing the directories or +# their entries' file path in the `include:` list. +# +# exclude: +# - .sass-cache/ +# - .jekyll-cache/ +# - gemfiles/ +# - Gemfile +# - Gemfile.lock +# - node_modules/ +# - vendor/bundle/ +# - vendor/cache/ +# - vendor/gems/ +# - vendor/ruby/ diff --git a/jekyll/icon.png b/jekyll/icon.png new file mode 100644 index 000000000..ad0a7e076 Binary files /dev/null and b/jekyll/icon.png differ diff --git a/jekyll/images/ruby-lsp-completion-demo-basic.mp4 b/jekyll/images/ruby-lsp-completion-demo-basic.mp4 new file mode 100644 index 000000000..c7de52166 Binary files /dev/null and b/jekyll/images/ruby-lsp-completion-demo-basic.mp4 differ diff --git a/jekyll/images/ruby-lsp-definition-demo-basic.mp4 b/jekyll/images/ruby-lsp-definition-demo-basic.mp4 new file mode 100644 index 000000000..17c7a2bf4 Binary files /dev/null and b/jekyll/images/ruby-lsp-definition-demo-basic.mp4 differ diff --git a/jekyll/images/ruby-lsp-definition-demo-multi-source.mp4 b/jekyll/images/ruby-lsp-definition-demo-multi-source.mp4 new file mode 100644 index 000000000..f39cf9ddf Binary files /dev/null and b/jekyll/images/ruby-lsp-definition-demo-multi-source.mp4 differ diff --git a/jekyll/images/ruby-lsp-erb-support-demo.mp4 b/jekyll/images/ruby-lsp-erb-support-demo.mp4 new file mode 100644 index 000000000..1b2878b54 Binary files /dev/null and b/jekyll/images/ruby-lsp-erb-support-demo.mp4 differ diff --git a/jekyll/images/ruby-lsp-hover-demo-basic.mp4 b/jekyll/images/ruby-lsp-hover-demo-basic.mp4 new file mode 100644 index 000000000..9b46857b2 Binary files /dev/null and b/jekyll/images/ruby-lsp-hover-demo-basic.mp4 differ diff --git a/jekyll/images/ruby-lsp-signature-help-demo-basic.mp4 b/jekyll/images/ruby-lsp-signature-help-demo-basic.mp4 new file mode 100644 index 000000000..0a203f229 Binary files /dev/null and b/jekyll/images/ruby-lsp-signature-help-demo-basic.mp4 differ diff --git a/jekyll/images/ruby-lsp-type-hierarchy-demo.mp4 b/jekyll/images/ruby-lsp-type-hierarchy-demo.mp4 new file mode 100644 index 000000000..047d293f9 Binary files /dev/null and b/jekyll/images/ruby-lsp-type-hierarchy-demo.mp4 differ diff --git a/jekyll/index.markdown b/jekyll/index.markdown new file mode 100644 index 000000000..3101571ab --- /dev/null +++ b/jekyll/index.markdown @@ -0,0 +1,237 @@ +--- +# Feel free to add content and custom Front Matter to this file. +# To modify the layout, see https://jekyllrb.com/docs/themes/#overriding-theme-defaults + +layout: minimal +title: Features +--- + +# Ruby LSP + +

+ Ruby LSP logo +

+ +The Ruby LSP is an implementation of the [language server protocol](https://microsoft.github.io/language-server-protocol/) +for Ruby, used to improve rich features in editors. It is a part of a wider goal to provide a state-of-the-art +experience to Ruby developers using modern standards for cross-editor features, documentation and debugging. + +Want to discuss Ruby developer experience? Consider joining the public +[Ruby DX Slack workspace](https://join.slack.com/t/ruby-dx/shared_invite/zt-2c8zjlir6-uUDJl8oIwcen_FS_aA~b6Q). + +## Table of Contents + +- [Usage](#usage) + - [With VS Code](#with-vs-code) + - [With other editors](#with-other-editors) +- [Addons](#addons) +- [Features](#features) + - [Hover](#hover) + - [Go-to-Definition](#go-to-definition) + - [Completion](#completion) + - [Signature Help](#signature-help) + - [Code Navigation in `.erb` Files](#code-navigation-in-erb-files) +- [Experimental Features](#experimental-features) + - [Ancestors Hierarchy Request](#ancestors-hierarchy-request) + - [Guess Type](#guess-type) +- [Configuration](#configuration) + - [Configuring code indexing](#configuring-code-indexing) +- [Additional Resources](#additional-resources) + +## Usage + +### With VS Code + +If using VS Code, all you have to do is install the [Ruby LSP +extension](https://marketplace.visualstudio.com/items?itemName=Shopify.ruby-lsp) to get the extra features in the +editor. Do not install the `ruby-lsp` gem manually. + +For more information on using and configuring the extension, see the extension's [README.md](https://github.com/Shopify/ruby-lsp/blob/main/vscode/README.md). + +### With other editors + +See [editors](https://github.com/Shopify/ruby-lsp/blob/main/EDITORS.md) for community instructions on setting up the Ruby LSP, which current includes Emacs, Neovim, Sublime Text, and Zed. + +The gem can be installed by doing + +```shell +gem install ruby-lsp +``` + +and the language server can be launched running `ruby-lsp` (without bundle exec in order to properly hook into your +project's dependencies). + +## Addons + +The Ruby LSP provides an addon system that allows other gems to enhance the base functionality with more editor +features. This is the mechanism that powers addons like + +- [Ruby LSP Rails](https://github.com/Shopify/ruby-lsp-rails) +- [Ruby LSP RSpec](https://github.com/st0012/ruby-lsp-rspec) +- [Ruby LSP rubyfmt](https://github.com/jscharf/ruby-lsp-rubyfmt) + +Additionally, some tools may include a Ruby LSP addon directly, like + +- [Standard Ruby (from v1.39.1)](https://github.com/standardrb/standard/wiki/IDE:-vscode#using-ruby-lsp) + +Other community driven addons can be found in [rubygems](https://rubygems.org/search?query=name%3A+ruby-lsp) by +searching for the `ruby-lsp` prefix. + +For instructions on how to create addons, see the [addons documentation](https://github.com/Shopify/ruby-lsp/blob/main/ADDONS.md). + +## Features + +### Hover + +The hover feature displays comments or documentation for the target constant or method when the cursor hovers over them. + +In VS Code, if you hover while pressing `Command`, it will also send a `definition` request to locate the possible target sources. And it will display the target's source code if only one source is located (e.g., the class is not reopened in multiple places). + + + +### Go-to-Definition + +Go-to-definition allows users to navigate to the target constant or method's definition, +whether they're defined in your project or its dependencies. + +This feature can be triggered by one of the following methods: + +- `Right click` on the target, and then select `Go to Definition` +- Placing the cursor on the target, and then hit `F12` +- `Command + click` the target + +**With One Definition:** + +Users are taken directly to the source. + + + +**With Multiple Definitions:** + +Users see a dropdown with all the sources, along with a preview window on the side. + + + +### Completion + +The completion feature provides users with completion candidates when the text they type matches certain indexed components. This helps speed up coding by reducing the need to type out full method names or constants. +It also allows developers to discover constants or methods that are available to them. + + + +### Signature Help + +Signature help often appears right after users finish typing a method, providing hints about the method's parameters. This feature is invaluable for understanding the expected arguments and improving code accuracy. + + + +### Code Navigation in `.erb` Files + +Code navigation features, like hover, go-to-definition, completion, and signature help, are supported in `.erb` files. + + + +## Experimental Features + +Ruby LSP also provides experimental features that are not enabled by default. If you have feedback about these features, +you can let us know in the [DX Slack](https://join.slack.com/t/ruby-dx/shared_invite/zt-2c8zjlir6-uUDJl8oIwcen_FS_aA~b6Q) or by [creating an issue](https://github.com/Shopify/ruby-lsp/issues/new). + +### Ancestors Hierarchy Request + +The ancestors hierarchy request feature aims to provide a better understanding of the inheritance hierarchy within your Ruby code. This feature helps developers trace the lineage of their classes and modules, making it easier to: + +- Visualize the inheritance hierarchy of classes and modules. +- Quickly navigate through the inheritance chain. + + + +#### Why Is It Experimental? + +This feature is supported by the [Type Hierarchy Supertypes LSP request](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#typeHierarchy_supertypes). During implementation, we encountered some ambiguities when applying it to Ruby. For example: + +- Should the list include only classes (pure inheritance chain), or should it include modules too (current behavior)? +- How should the inheritance chain of singleton classes be triggered and displayed? +- If a class or module is reopened multiple times, it will appear multiple times in the list. In real-world applications, this can make the list very long. + +We created [an issue](https://github.com/microsoft/language-server-protocol/issues/1984) to seek clarification from the LSP maintainers. We will adjust this feature's design and behavior based on their response and your feedback. + +### Guess Type + +The guess type feature is an experimental addition to Ruby LSP that attempts to identify the type of a receiver based on its identifier name. This helps improve code completion and navigation by providing type information. + +This feature is disabled by default but can be enabled with the `rubyLsp.enableExperimentalFeatures` setting in VS Code. + +#### How It Works + +Ruby LSP guesses the type of a variable by matching its identifier name to a class. For example, a variable named `user` would be assigned the `User` type if such a class exists: + +```ruby +user.name # Guessed to be of type `User` +@post.like! # Guessed to be of type `Post` +``` + +By guessing the types of variables, Ruby LSP can expand the code navigation features to even more cases. + +#### Important Notes + +- Identifiers are not ideal for complex type annotations and can be easily misled by non-matching names. +- We do NOT recommend renaming identifiers just to make this feature work. + +For more information, please refer to the [documentation](https://github.com/Shopify/ruby-lsp/blob/main/DESIGN_AND_ROADMAP.md#guessed-types). + +## Configuration + +### Configuring code indexing + +By default, the Ruby LSP indexes all Ruby files defined in the current project and all of its dependencies, including +default gems, except for + +- Gems that only appear under the `:development` group +- All Ruby files under `test/**/*.rb` + +This behaviour can be overridden and tuned. Learn how to configure it [for VS Code](https://github.com/Shopify/ruby-lsp/tree/main/vscode#indexing-configuration). + +Note that indexing-dependent behavior, such as definition, hover, completion or workspace symbol will be impacted by +the configuration changes. + +The older approach of using a `.index.yml` file has been deprecated and will be removed in a future release. + +```yaml +# Exclude files based on a given pattern. Often used to exclude test files or fixtures +excluded_patterns: + - "**/spec/**/*.rb" + +# Include files based on a given pattern. Can be used to index Ruby files that use different extensions +included_patterns: + - "**/bin/*" + +# Exclude gems by name. If a gem is never referenced in the project's code and is only used as a tool, excluding it will +# speed up indexing and reduce the amount of results in features like definition or completion +excluded_gems: + - rubocop + - pathname + +# Include gems by name. Normally used to include development gems that are excluded by default +included_gems: + - prism +``` + +## Additional Resources + +* [RubyConf 2022: Improving the development experience with language servers](https://www.youtube.com/watch?v=kEfXPTm1aCI) ([Vinicius Stock](https://github.com/vinistock)) +* [Remote Ruby: Ruby Language Server with Vinicius Stock](https://remoteruby.com/221) +* [RubyKaigi 2023: Code indexing - How language servers understand our code](https://www.youtube.com/watch?v=ks3tQojSJLU) ([Vinicius Stock](https://github.com/vinistock)) diff --git a/sorbet/config b/sorbet/config index 255ce1452..8e0371cb5 100644 --- a/sorbet/config +++ b/sorbet/config @@ -4,4 +4,5 @@ --ignore=tmp/ --ignore=test/fixtures/ --ignore=test/expectations/ +--ignore=jekyll/ --enable-experimental-requires-ancestor