Skip to content

Commit 329bcd2

Browse files
aviateskaviatesk
committed
docs: Add features overview page
Add a new `docs/src/features.md` page that provides a visual overview of JETLS language server features with screenshots and descriptions. The page covers: - Diagnostics (syntax errors, lowering errors, unused bindings, etc.) - Completion (global/local, method signatures, keyword arguments, LaTeX/emoji) - Signature help with type-based filtering - Go to definition and find references - Hover, document highlight - Refactoring (rename, code actions) - Formatting, TestRunner integration, notebook support - Roadmap section linking to GitHub and development notes Also adds a brief "Features overview" section to `index.md` that links to the new features page.
1 parent da9b373 commit 329bcd2

File tree

4 files changed

+215
-3
lines changed

4 files changed

+215
-3
lines changed

‎docs/make.jl‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ let CHANGELOG_md = joinpath(@__DIR__, "..", "CHANGELOG.md")
4040
s"""
4141
```@raw html
4242
<center>
43-
<iframe style="width:100%;height:min(500px,70vh);aspect-ratio:16/9" src="\1" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
43+
<iframe style="width:100%;height:min(500px,70vh);aspect-ratio:16/9" src="\1" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
4444
</center>
4545
```
4646
""")
@@ -59,6 +59,7 @@ end
5959

6060
const pages = Any[
6161
"Index" => "index.md",
62+
"Features" => "features.md",
6263
"Diagnostic" => "diagnostic.md",
6364
"Formatter integration" => "formatting.md",
6465
"TestRunner integration" => "testrunner.md",

‎docs/src/features.md‎

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
# [Features](@id features)
2+
3+
JETLS aims to be a fully-featured language server for Julia, providing advanced
4+
static analysis and seamless integration with the Julia runtime, leveraging
5+
recent tooling technologies like [JET.jl](https://github.com/aviatesk/JET.jl),
6+
[JuliaSyntax.jl](https://github.com/JuliaLang/JuliaSyntax.jl) and
7+
[JuliaLowering.jl](https://github.com/c42f/JuliaLowering.jl)
8+
9+
## [Diagnostic](@id features/diagnostic)
10+
11+
JETLS reports various diagnostics including:
12+
13+
- Syntax errors
14+
- Lowering errors and macro expansion errors
15+
- Unused bindings (arguments, locals)
16+
- Method overwrites
17+
- Abstract struct fields
18+
- Undefined global variables
19+
- Non-existent struct fields
20+
- Out-of-bounds field access
21+
22+
> Syntax/lowering error (Zed)
23+
> ```@raw html
24+
> <center>
25+
> <iframe class="display-light-only" style="width:100%;height:min(500px,70vh);aspect-ratio:16/9" src="https://github.com/user-attachments/assets/a29db5d0-fa53-4958-ab3d-a9ab4952a0ef" alt="Syntax/lowering diagnostic" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
26+
> <iframe class="display-dark-only" style="width:100%;height:min(500px,70vh);aspect-ratio:16/9" src="https://github.com/user-attachments/assets/7c291dde-8ab6-44f5-bce4-0e3478ff2018" alt="Syntax/lowering diagnostic" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
27+
> </center>
28+
> ```
29+
30+
> Abstract field (VSCode)
31+
> ```@raw html
32+
> <center>
33+
> <img class="display-light-only" alt="Diagnostic abstract field" src="https://github.com/user-attachments/assets/d2c80efb-5e34-4180-95e2-ee1df4fc93f6">
34+
> <img class="display-dark-only" alt="Diagnostic abstract field" src="https://github.com/user-attachments/assets/0efec540-9d86-4887-a4d9-a49fbad03560">
35+
> </center>
36+
> ```
37+
38+
Some diagnostics offer quickfix [code actions](@ref features/refactoring/code-actions),
39+
such as prefixing unused variables with `_` to suppress warnings.
40+
41+
For detailed diagnostic reference and configuration options, see
42+
the [diagnostic section](@ref diagnostic).
43+
44+
## [Completion](@id features/completion)
45+
46+
JETLS provides powerful and intelligent code completion with type-aware suggestions.
47+
48+
### [Global and local completion](@id features/completion/global-local)
49+
50+
Completion for global symbols (functions, types, modules, constants) and local
51+
bindings. Global completions include detailed kind information resolved lazily
52+
when selected.
53+
54+
> Global and local completion (Zed)
55+
> ```@raw html
56+
> <center>
57+
> <iframe class="display-light-only" style="width:100%;height:min(00px,70vh);aspect-ratio:16/7" src="https://github.com/user-attachments/assets/076769bd-3241-4c12-a165-f3ec7c5cd958" alt="Global and local completion" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
58+
> <iframe class="display-dark-only" style="width:100%;height:min(500px,70vh);aspect-ratio:16/7" src="https://github.com/user-attachments/assets/533674d0-e488-4639-b953-015158064c82" alt="Global and local completion" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
59+
> </center>
60+
> ```
61+
62+
### [Method signature completion](@id features/completion/method-signature)
63+
64+
When typing inside a function call (triggered by `(`, `,`, or space), compatible
65+
method signatures are suggested based on already-provided arguments. Selecting
66+
a completion inserts remaining positional arguments as snippet placeholders with
67+
type annotations. Inferred return type and documentation are resolved lazily.
68+
69+
> Method signature completion (VSCode)
70+
> ```@raw html
71+
> <center>
72+
> <iframe class="display-light-only" style="width:100%;height:min(500px,70vh);aspect-ratio:16/9" src="https://github.com/user-attachments/assets/fd72a4ee-4bb5-4cd6-a9a0-f0d669d9c065" alt="Method signature completion" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
73+
> <iframe class="display-dark-only" style="width:100%;height:min(500px,70vh);aspect-ratio:16/9" src="" alt="Method signature completion" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
74+
> </center>
75+
> ```
76+
77+
### [Keyword argument completion](@id features/completion/keyword-argument)
78+
79+
When typing inside a function call (e.g., `func(; |)` or `func(k|)`), available
80+
keyword arguments are suggested with `=` appended. Already-specified keywords
81+
are excluded from suggestions.
82+
83+
> Keyword argument completion (VSCode)
84+
> ```@raw html
85+
> <center>
86+
> <iframe class="display-light-only" style="width:100%;height:min(500px,70vh);aspect-ratio:16/9" src="https://github.com/user-attachments/assets/1e58bee2-e682-47d2-81e8-0553a620428a" alt="Keyword argument completion" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
87+
> <iframe class="display-dark-only" style="width:100%;height:min(500px,70vh);aspect-ratio:16/9" src="https://github.com/user-attachments/assets/1fe8e695-e24a-4e62-b0bc-7027459ed3c9" alt="Keyword argument completion" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
88+
> </center>
89+
> ```
90+
91+
### [LaTeX and emoji completion](@id features/completion/latex-emoji)
92+
93+
Type `\` to trigger LaTeX symbol completion (e.g., `\alpha` → `α`) or `\:`
94+
to trigger emoji completion (e.g., `\:smile:` → `😄`), mirroring the behavior
95+
of the Julia REPL.
96+
97+
> LaTeX emoji completion (Zed)
98+
> ```@raw html
99+
> <center>
100+
> <img class="display-light-only" alt="LaTeX emoji completion" src="https://github.com/user-attachments/assets/0b074bc7-97a9-405b-8695-dd69a051f59a">
101+
> <img class="display-dark-only" alt="LaTeX emoji completion" src="https://github.com/user-attachments/assets/20e88f56-8d9f-4f32-bff4-8cf9ffac8602">
102+
> </center>
103+
> ```
104+
105+
## [Signature help](@id features/signature-help)
106+
107+
JETLS displays method signatures as you type function arguments. Methods are
108+
filtered based on the inferred types of already-provided arguments. For example,
109+
typing `sin(1,` shows only methods compatible with an `Int` first argument.
110+
111+
## [Go to definition](@id features/go-to-definition)
112+
113+
Jump to where a symbol is defined. JETLS resolves method or module definitions,
114+
and local bindings.
115+
116+
```@raw html
117+
<center>
118+
<img class="display-light-only" alt="Go to definition" src="https://github.com/user-attachments/assets/78d89486-4bc1-4faa-8d19-8dfb142bc046">
119+
<img class="display-dark-only" alt="Go to definition" src="https://github.com/user-attachments/assets/555008e7-27e4-444d-b72b-76607db639c8">
120+
</center>
121+
```
122+
123+
## [Find references](@id features/find-references)
124+
125+
Find all references to a symbol within the same analysis unit. Both local and
126+
global bindings are supported.
127+
128+
```@raw html
129+
<center>
130+
<img class="display-light-only" alt="Find references" src="https://github.com/user-attachments/assets/bcca21b3-a4cb-40fe-8f92-071a370e7255">
131+
<img class="display-dark-only" alt="Find references" src="https://github.com/user-attachments/assets/95099e0b-f56b-437b-aabe-d10647292aca">
132+
</center>
133+
```
134+
135+
## [Hover](@id features/hover)
136+
137+
Hover over symbols to see documentation and source locations. Method
138+
documentation includes signature information and docstrings. Local bindings
139+
show their definition location.
140+
141+
## [Document highlight](@id features/document-highlight)
142+
143+
Select a symbol to highlight all its occurrences in the current file.
144+
145+
## [Refactoring](@id features/refactoring)
146+
147+
### [Rename](@id features/refactoring/rename)
148+
149+
Rename local or global bindings across files. When renaming a string literal
150+
that refers to a file path (e.g., in `include("foo.jl")`), JETLS also renames
151+
the file on disk.
152+
153+
### [Code actions](@id features/refactoring/code-actions)
154+
155+
JETLS provides code actions for quick fixes and refactoring:
156+
157+
- Prefix unused variables with `_` to suppress warnings
158+
- Delete unused variable assignments (removes `y = `, keeping the RHS expression)
159+
- Delete unused assignment statements entirely
160+
161+
## [Formatting](@id features/formatting)
162+
163+
JETLS integrates with external formatters:
164+
165+
- [Runic.jl](https://github.com/fredrikekre/Runic.jl) (default)
166+
- [JuliaFormatter.jl](https://github.com/domluna/JuliaFormatter.jl)
167+
168+
See [Formatting](@ref "Formatting") for setup instructions.
169+
170+
## [TestRunner integration](@id features/testrunner)
171+
172+
Run individual `@testset` blocks and `@test` cases directly from your editor
173+
via code lenses and code actions.
174+
175+
See [TestRunner integration](@ref "TestRunner integration") for setup
176+
instructions.
177+
178+
## [Notebook support](@id features/notebook)
179+
180+
JETLS provides full LSP features for Julia code cells in Jupyter notebooks.
181+
All cells are analyzed together, so features like go-to-definition, completions,
182+
and diagnostics work across cells.
183+
184+
> Demo in VSCode
185+
>
186+
> ```@raw html
187+
> <center>
188+
> <iframe class="display-light-only" style="width:100%;height:min(500px,70vh);aspect-ratio:16/9" src="https://github.com/user-attachments/assets/b5bb5201-d735-4a37-b430-932b519254ee" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
189+
> <iframe class="display-dark-only" style="width:100%;height:min(500px,70vh);aspect-ratio:16/9" src="https://github.com/user-attachments/assets/f7476257-7a53-44a1-8c8c-1ad57e136a63" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
190+
> </center>
191+
> ```
192+
193+
See [Notebook support](@ref notebook) for details.
194+
195+
## Roadmap
196+
197+
JETLS is under active development. Features like inlay hints, workspace symbols,
198+
and type-aware method definitions are planned but not yet implemented.
199+
200+
For the full list of planned features and current progress, see the
201+
[roadmap on GitHub](https://github.com/aviatesk/JETLS.jl?tab=readme-ov-file#roadmap)
202+
or the [development notes](https://publish.obsidian.md/jetls/work/JETLS/JETLS+roadmap).

‎docs/src/index.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,15 @@ diagnostic, macro-aware go-to definition and such.
1616
Not production-ready; APIs and behavior may change.
1717
Stability and performance are limited. Expect bugs and rough edges.
1818

19+
## Features overview
20+
21+
JETLS aims to be a fully-featured language server for Julia, providing
22+
comprehensive [language server features](https://microsoft.github.io/language-server-protocol/)
23+
including diagnostics, code completion, signature help, go-to definition,
24+
find references, rename, hover, formatting, and more.
25+
26+
See [Features](@ref features) for visual demonstrations of each feature.
27+
1928
## Server installation
2029

2130
Editor clients for JETLS generally do not bundle the JETLS server itself.

‎docs/src/notebook.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,8 @@ state of client implementations
1616

1717
```@raw html
1818
<center>
19-
<iframe class="display-light-only" style="width:100%;height:min(500px,70vh);aspect-ratio:16/9" src="https://github.com/user-attachments/assets/b5bb5201-d735-4a37-b430-932b519254ee" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
20-
<iframe class="display-dark-only" style="width:100%;height:min(500px,70vh);aspect-ratio:16/9" src="https://github.com/user-attachments/assets/f7476257-7a53-44a1-8c8c-1ad57e136a63" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
19+
<iframe class="display-light-only" style="width:100%;height:min(500px,70vh);aspect-ratio:16/9" src="https://github.com/user-attachments/assets/b5bb5201-d735-4a37-b430-932b519254ee" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
20+
<iframe class="display-dark-only" style="width:100%;height:min(500px,70vh);aspect-ratio:16/9" src="https://github.com/user-attachments/assets/f7476257-7a53-44a1-8c8c-1ad57e136a63" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
2121
</center>
2222
```
2323

0 commit comments

Comments
 (0)