Rewrite plugin tutorial #3655
Rewrite plugin tutorial #3655
Conversation
cgeorgii
requested review from
michaelpj,
pepeiborra and
berberman
as code owners
cgeorgii
force-pushed
the
plugin-tutorial
branch
from
d60b483
to
de688f2
Compare
|
What do you think about taking this opportunity to make the code snippets compiled? RST lets you include chunks from files, so it's relatively easy to define a separate source file and include the snippets from it, and then we can compile that source file to make sure the examples keep working. |
|
@michaelpj lots of the shown code is code from HLS directly, e.g. types from the PluginDescriptor. What might be possible is to compile the actual plugin, but everything else is unlikely to work, I think. |
I think we might just be able to include the relevant section from the files in HLS also! |
|
Referencing a code section from another file? Do you have an example of how we could do that? |
|
See the use of You just give it the path to a file, it has various ways of selecting what chunk to include into the doc. So we can have:
|
|
Yep, I'll try to do it :) |
|
As far as I can tell the |
|
That sounds good to me! |
|
|
||
| Providers are functions that receive some inputs and produce an IO computation that returns either an error or some result. | ||
| > **Note**: Check the [LSP spec](https://microsoft.github.io/language-server-protocol/specification) for a deeper understanding of how commands work. |
There was a problem hiding this comment.
Another reason I like RST: proper support for admonitions like this.
There was a problem hiding this comment.
I created an issue to track this.
docs/contributing/plugin-tutorial.md
Outdated
| ### The command handler | ||
|
|
||
| Our plugin provider has two components that need to be fleshed out. Let's start with the command provider, since it's the simplest of the two. | ||
| The most important (and still `undefined`) field is `commandFunc :: CommandFunction`, another type synonym from `LSP.Types`: |
There was a problem hiding this comment.
| The most important (and still `undefined`) field is `commandFunc :: CommandFunction`, another type synonym from `LSP.Types`: | |
| The most important (and still `undefined`) field is `commandFunc :: CommandFunction`, a type synonym from `LSP.Types`: |
cgeorgii
force-pushed
the
plugin-tutorial
branch
from
de688f2
to
e3155c6
Compare
|
|
||
| - The `ormolu`, `fourmolu`, `floskell` and `stylish-haskell` plugins | ||
| - The `eval` plugin, a code lens provider to evaluate code in comments | ||
| - The `retrie` plugin, a code actions provider to execute retrie commands |
There was a problem hiding this comment.
| - The `retrie` plugin, a code actions provider to execute retrie commands | |
| - The `retrie` plugin, a code action provider to execute retrie commands |
| 2. Extract the actual import lists from the type checked AST, | ||
| 3. Ask GHC to produce the minimal import lists for this AST, | ||
| 4. For every import statement without a explicit import list, find out the minimal import list, and produce a code lens to display it together with a command to graft it on. | ||
| 4. For every import statement without a explicit import list: |
There was a problem hiding this comment.
| 4. For every import statement without a explicit import list: | |
| 4. For every import statement without an explicit import list: |
| Once cabal is done take a note of the location of the `haskell-language-server` binary and point your LSP client to it. In VSCode this is done by editing the "Haskell Server Executable Path" setting. This way you can simply test your changes by reloading your editor after rebuilding the binary. | ||
|
|
||
|  | ||
| Make sure you use the HLS package you just built by following [this section](https://haskell-language-server.readthedocs.io/en/latest/contributing/contributing.html#manually-testing-your-hacked-hls) of the "Contributing" guide. |
There was a problem hiding this comment.
| Make sure you use the HLS package you just built by following [this section](https://haskell-language-server.readthedocs.io/en/latest/contributing/contributing.html#manually-testing-your-hacked-hls) of the "Contributing" guide. | |
| Make sure you use the HLS package you just built by following [this section](https://haskell-language-server.readthedocs.io/en/latest/contributing/contributing.html#manually-testing-your-hacked-hls) of the Contributing section. |
For consistency, since the Contributing section is also mentioned above.
| * Commands are an LSP abstraction for actions initiated by the user which are handled in the server. These actions can be long running and involve multiple modules. Many plugins define command handlers. | ||
| * Providers are a query-like abstraction where the LSP client asks the server for information. These queries must be fulfilled as quickly as possible. | ||
| * Request handlers are called when an LSP client asks the server for information. These queries must be fulfilled as quickly as possible. | ||
| * Notification handlers are called by code that was not directly triggerd by an user/client. |
There was a problem hiding this comment.
| * Notification handlers are called by code that was not directly triggerd by an user/client. | |
| * Notification handlers are called by code that was not directly triggered by a user/client. |
|
|
||
| -- | A GHC session that we reuse. | ||
| type instance RuleResult GhcSession = HscEnvEq | ||
| In short, commands works like this: |
There was a problem hiding this comment.
| In short, commands works like this: | |
| In short, commands work like this: |
|
(am very interested in this, as am trying to work through the tutorial myself!) |
|
I'll try to get back to this soon! |
This is an almost-complete rewrite of the outdated plugin tutorial. The section about the code lens provider is still unchanged and probably incorrect. I'll try to get to it at some point.
To view the new docs locally follow the instructions from the docs. TLDR:
cd docs; make htmlIt also contains some minor refactors to the files mentioned in the plugin since it aided in my understanding of what was going on.