Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add infrastructure for keyword documentation #2581

Merged
merged 1 commit into from
Oct 1, 2024

Conversation

vinistock
Copy link
Member

Motivation

This PR adds the basic infrastructure for #2227, so that we can slowly document keywords and even receive help from the community in doing so.

Implementation

The idea is to show a short sentence on hover/completion with a link to longer form documentation.

The way I went about this is to add a separate directory with all of the static documentation in Markdown files. Those files are never read by the LSP, we just link to them from the hover markdown. Clicking on the link will open the documentation on the user's editor.

After this infrastructure is merged, the work to document more keywords is simply:

  1. Add the related Prism class to the list of ALLOWED_TARGETS
  2. Register for the event on the dispatcher (e.g.: :on_next_node_enter)
  3. Define the exact same handler as yield
sig { params(node: Prism::SomeKeywordNode).void }
def on_some_keyword_node_enter(node)
  show_keyword_documentation(node.keyword)
end
  1. Write both the short and long documentation, in static_docs.rb and static_docs/some_keyword.md, respectively

Automated Tests

Added tests.

Manual Tests

  1. On this branch, hover over yield
  2. Verify you see the documentation
  3. Click the read more link
  4. Verify you land on the yield.md file

@vinistock vinistock added enhancement New feature or request server This pull request should be included in the server gem's release notes labels Sep 19, 2024
@vinistock vinistock self-assigned this Sep 19, 2024
@vinistock vinistock requested a review from a team as a code owner September 19, 2024 21:07
@vinistock vinistock requested a review from andyw8 September 19, 2024 21:07
@vinistock vinistock force-pushed the vs-add-yield-documentation branch from f153516 to b60651e Compare September 20, 2024 19:49
@vinistock vinistock force-pushed the vs-add-yield-documentation branch from b60651e to 0c9c5e3 Compare September 30, 2024 18:28
lib/ruby_lsp/listeners/hover.rb Outdated Show resolved Hide resolved
lib/ruby_lsp/static_docs.rb Outdated Show resolved Hide resolved
static_docs/yield.md Outdated Show resolved Hide resolved
@vinistock vinistock force-pushed the vs-add-yield-documentation branch from 0c9c5e3 to bed994c Compare October 1, 2024 13:03
@vinistock vinistock enabled auto-merge (squash) October 1, 2024 13:04
@vinistock vinistock merged commit c00f2bc into main Oct 1, 2024
33 checks passed
@vinistock vinistock deleted the vs-add-yield-documentation branch October 1, 2024 13:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request server This pull request should be included in the server gem's release notes
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants