Rework features documentation

michaelpj · michaelpj · commit 73eef27216f6 · 2022-01-19T14:07:38.000Z
This does a few things:
- Adds a clear listing of which LSP methods we support, and which we
don't (requested a couple of times recently).
- Lists every code action and code lens, which plugin provies them,
their status, and code action kind where applicable (apart from Wingman
because there are lots and I couldn't figure it all out).

Possibly some of this information belongs elsewhere, e.g. perhaps
instead of listing which versions don't have full support on this page,
we should instead add a page to the GHC support page that lists which
plugins work on which versions. Not sure.
diff --git a/docs/_static/theme_overrides.css b/docs/_static/theme_overrides.css
@@ -0,0 +1,6 @@
+/* Fix table wrapping https://github.com/readthedocs/sphinx_rtd_theme/issues/117 */
+@media screen and (min-width: 768px) {
+	.wy-table-responsive table td, .wy-table-responsive table th {
+	  white-space: normal !important;
+	}
+}
diff --git a/docs/conf.py b/docs/conf.py
@@ -86,4 +86,9 @@
 
 # Enable linking to an anchor of a relative page
 # See https://github.com/executablebooks/MyST-Parser/issues/443
-myst_heading_anchors = 2
+myst_heading_anchors = 3
+
+# -- Custom Document processing ----------------------------------------------
+
+def setup(app):
+    app.add_css_file("theme_overrides.css")
diff --git a/docs/features.md b/docs/features.md
@@ -1,58 +1,266 @@
 # Features
 
-You can watch demos for some of these features [below](#demos).
-
-- Warning and error diagnostics from GHC
-- Type information and documentation on hover, [including your own comments](./configuration.md#how-to-show-local-documentation-on-hover).
-- Jump to definition: [for now only for local code definitions](https://github.com/haskell/haskell-language-server/issues/708)
-- Document symbols
-- Highlight references in document
-- Code completion
-- Formatting via [Brittany](https://github.com/lspitzner/brittany), [Floskell](https://github.com/ennocramer/floskell), [Fourmolu](https://github.com/fourmolu/fourmolu), [Ormolu](https://github.com/tweag/ormolu) or [Stylish Haskell](https://github.com/haskell/stylish-haskell)
-- [Code evaluation](#code-evaluation), see its [Tutorial](https://github.com/haskell/haskell-language-server/blob/master/plugins/hls-eval-plugin/README.md)
-- [Integration with](#retrie-integration) [retrie](https://hackage.haskell.org/package/retrie), a powerful, easy-to-use codemodding tool
-- [Code lenses for explicit import lists](#explicit-import-lists)
-- [Generate functions from type signatures, and intelligently complete holes](#wingman) using [Wingman (tactics)](https://github.com/haskell/haskell-language-server/tree/master/plugins/hls-tactics-plugin)
-- [Integration](#hlint) with [hlint](https://github.com/ndmitchell/hlint), the most used haskell linter, to show diagnostics and apply hints via [apply-refact](https://github.com/mpickering/apply-refact)
-- [Module name suggestions](#module-names) for insertion or correction
-- [Call hierarchy support](#call-hierarchy)
-- [Qualify names from an import declaration](#qualify-imported-names) in your code
-- [Suggest alternate numeric formats](#alternate-number-formatting)
-
-## Demos
-
-### Code evaluation
+This table gives a summary of the features that HLS supports.
+Many of these are standard LSP features, but a lot of special features are provided as [code actions](#code-actions) and [code lenses](#code-lenses).
 
-![Eval Demo](https://raw.githubusercontent.com/haskell/haskell-language-server/master/plugins/hls-eval-plugin/demo.gif)
+| Feature                                             | Status                          | [LSP method](./what-is-hls.md#lsp-terminology)                                                    |
+|-----------------------------------------------------|---------------------------------|---------------------------------------------------------------------------------------------------|
+| [Diagnostics](#diagnostics)                         | Limited on some versions of GHC | `textDocument/publishDiagnostics`                                                                 |
+| [Hovers](#hovers)                                   | Working                         | `textDocument/hover`                                                                              |
+| [Jump to definition](#jump-to-definition)           | Working                         | `textDocument/definition`                                                                         |
+| [Jump to type definition](#jump-to-type-definition) | Working                         | `textDocument/typeDefinition`                                                                     |
+| [Find references](#find-references)                 | Working                         | `textDocument/references`                                                                         |
+| [Completions](#completions)                         | Working                         | `textDocument/completion`                                                                         |
+| [Formatting](#formatting)                           | Limited on some versions of GHC | `textDocument/formatting`, `textDocument/rangeFormatting`                                         |
+| [Document symbols](#document-symbols)               | Working                         | `textDocument/documentSymbol`                                                                     |
+| [Workspace symbols](#workspace-symbols)             | Working                         | `workspace/symbol`                                                                                |
+| [Call hierarchy](#call-hierarchy)                   | Working                         | `textDocument/prepareCallHierarchy`, `callHierarchy/incomingCalls`, `callHierarchy/outgoingCalls` |
+| [Highlight references](#highlight-references)       | Working                         | `textDocument/documentHighlight`                                                                  |
+| [Code actions](#code-actions)                       | Limited on some versions of GHC | `textDocument/codeAction`                                                                         |
+| [Code lenses](#code-lenses)                         | Limited on some versions of GHC | `textDocument/codeLens`                                                                           |
 
-### Retrie integration
+The individual sections below also identify which [HLS plugin](./what-is-hls.md#hls-plugins) is responsible for providing the given functionality, which is useful if you want to raise an issue report or contribute!
 
-![Retrie Demo](https://i.imgur.com/Ev7B87k.gif)
+## Diagnostics
 
-### Explicit import lists
+### GHC compiler errors and warnings
+Provided by: `ghcide`
 
-![Imports code lens Demo](https://imgur.com/pX9kvY4.gif)
+Provides errors and warnings from GHC as diagnostics.
 
-### Wingman
+### Hlint hints
+Status: Not supported on GHC 9.2
 
-![Wingman Demo](https://user-images.githubusercontent.com/307223/92657198-3d4be400-f2a9-11ea-8ad3-f541c8eea891.gif)
+Provided by: `hls-hlint-plugin`
 
-### Hlint
+Provides hlint hints as diagnostics.
 
-![Hlint Demo](https://user-images.githubusercontent.com/54035/110860028-8f9fa900-82bc-11eb-9fe5-6483d8bb95e6.gif)
+## Hovers
+Provided by: `ghcide`
 
-### Module names
+Type information and documentation on hover, [including from local definitions](./configuration.md#how-to-show-local-documentation-on-hover).
 
-![Module Name Demo](https://user-images.githubusercontent.com/54035/110860755-78ad8680-82bd-11eb-9845-9ea4b1cc1f76.gif)
+## Jump to definition
+Provided by: `ghcide`
+
+Jump to definition, [for now only for local code definitions](https://github.com/haskell/haskell-language-server/issues/708).
+
+## Jump to type definition
+Provided by: `ghcide`
+
+## Find references
+Provided by: `ghcide`
+
+Find references to a name within the project.
+
+## Completions
 
-### Call hierarchy
+### Code completions
+Provided by: `ghcide`
+
+- Completion of names from qualified imports.
+- Completion of names from non-imported modules.
+
+### Pragma completions
+Provided by: `hls-pragmas-plugin`
+
+Completions for language pragmas.
+
+## Formatting
+Format your code with various Haskell code formatters.
+
+| Formatter       | Status                          | Provided by                  |
+|-----------------|---------------------------------|------------------------------|
+| Brittany        | Not supported on GHC 9.2        | `hls-brittany-plugin`        |
+| Floskell        | Working                         | `hls-floskell-plugin`        |
+| Fourmolu        | Working                         | `hls-fourmolu-plugin`        |
+| Ormolu          | Working                         | `hls-ormolu-plugin`          |
+| Stylish Haskell | Not supported on GHC 9.0 or 9.2 | `hls-stylish-haskell-plugin` |
+
+## Document symbols
+Provided by: `ghcide`
+
+Provides listing of the symbols defined in a module, used to power outline displays.
+
+## Workspace symbols
+Provided by: `ghcide`
+
+Provides listing of the symbols defined in the project, used to power searches.
+
+## Call hierarchy
+Provided by: `hls-call-hierarchy-plugin`
+
+Shows ingoing and outgoing calls for a function.
 
 ![Call Hierarchy in VSCode](https://github.com/haskell/haskell-language-server/raw/2857eeece0398e1cd4b2ffb6069b05c4d2308b39/plugins/hls-call-hierarchy-plugin/call-hierarchy-in-vscode.gif)
 
+## Highlight references
+Provided by: `ghcide`
+
+Highlights references to a name in a document.
+
+## Code actions
+
+### Insert missing pragmas
+Provided by: `hls-pragma-plugin`
+
+Code action kind: `quickfix`
+
+Inserts missing pragmas needed by GHC.
+
+### Apply Hlint fixes
+Status: Not supported on GHC 9.2
+
+Provided by: `hls-hlint-plugin`
+
+Code action kind: `quickfix`
+
+Applies hints, either individually or for the whole file.
+Uses [apply-refact](https://github.com/mpickering/apply-refact).
+
+![Hlint Demo](https://user-images.githubusercontent.com/54035/110860028-8f9fa900-82bc-11eb-9fe5-6483d8bb95e6.gif)
+
+### Make import lists fully explicit
+Provided by: `hls-explicit-imports-plugin`
+
+Code action kind: `quickfix.literals.style`
+
+Make import lists fully explicit (same as the code lens).
+
 ### Qualify imported names
+Provided by: `hls-qualify-imported-names-plugin`
+
+Code action kind: `quickfix`
+
+Rewrites imported names to be qualified.
 
 ![Qualify Imported Names Demo](../plugins/hls-qualify-imported-names-plugin/qualify-imported-names-demo.gif)
 
-### Alternate Number Formatting
+### Refine import
+Provided by: `hls-refine-imports-plugin`
+
+Code action kind: `quickfix.import.refine`
+
+Refines imports to more specific modules when names are re-exported (same as the code lens).
+
+### Add missing class methods
+Status: Not supported on GHC 9.2
+
+Provided by: `hls-class-plugin`
+
+Code action kind: `quickfix`
+
+Adds placeholders for missing class methods in a class instance definition.
+
+### Unfold definition
+Status: Not supported on GHC 9.2
+
+Provided by: `hls-retrie-plugin`
+
+Code action kind: `refactor.extract`
+
+Extracts a definition from the code.
+
+### Fold definition
+Status: Not supported on GHC 9.2
+
+Provided by: `hls-retrie-plugin`
+
+Code action kind: `refactor.inline`
+
+Inlines a definition from the code.
+
+![Retrie Demo](https://i.imgur.com/Ev7B87k.gif)
+
+### Insert contents of Template Haskell splice
+Status: Not supported on GHC 9.2
+
+Provided by: `hls-splice-plugin`
+
+Code action kind: `refactor.rewrite`
+
+Evaluates a Template Haskell splice and inserts the resulting code in its place.
+
+### Convert numbers to alternative formats
+Status: Not supported on GHC 9.2
+
+Provided by: `hls-alternate-number-format-plugin`
+
+Code action kind: `quickfix.literals.style`
+
+Converts numeric literals to different formats.
 
 ![Alternate Number Format Demo](../plugins/hls-alternate-number-format-plugin/HLSAll.gif)
+
+### Add Haddock comments
+Status: Not supported on GHC 9.2
+
+Provided by: `hls-haddock-comments-plugin`
+
+Code action kind: `quickfix`
+
+Adds Haddock comments for function arguments.
+
+### Wingman
+Status: Not supported on GHC 9.2
+
+Provided by: `hls-tactics-plugin`
+
+Provides a variety of code actions for interactive code development, see https://haskellwingman.dev/ for more details.
+
+![Wingman Demo](https://user-images.githubusercontent.com/307223/92657198-3d4be400-f2a9-11ea-8ad3-f541c8eea891.gif)
+
+## Code lenses
+
+### Add type signature
+Provided by: `ghcide`
+
+Shows the type signature for bindings without type signatures, and adds it with a click.
+
+### Evaluation code snippets in comments
+Status: Not supported on GHC 9.2
+
+Provided by: `hls-eval-plugin`
+
+Evaluates code blocks in comments with a click. [Tutorial](https://github.com/haskell/haskell-language-server/blob/master/plugins/hls-eval-plugin/README.md).
+
+![Eval Demo](https://raw.githubusercontent.com/haskell/haskell-language-server/master/plugins/hls-eval-plugin/demo.gif)
+
+### Make import lists fully explicit
+Provided by: `hls-explicit-imports-plugin`
+
+Shows fully explicit import lists and rewrites them with a click (same as the code action).
+
+![Imports code lens Demo](https://imgur.com/pX9kvY4.gif)
+
+### Refine import
+Provided by: `hls-refine-imports-plugin`
+
+Shows refined imports and applies them with a click (same as the code action).
+
+### Fix module names
+Provided by: `hls-module-name-plugin`
+
+Shows module name matching file path, and applies it with a click.
+
+![Module Name Demo](https://user-images.githubusercontent.com/54035/110860755-78ad8680-82bd-11eb-9845-9ea4b1cc1f76.gif)
+
+## Missing features
+
+The following features are supported by the LSP specification but not implemented in HLS.
+Contributions welcome!
+
+| Feature                | Status                                                                                   | [LSP method](./what-is-hls.md#lsp-terminology)      |
+|------------------------|------------------------------------------------------------------------------------------|-----------------------------------------------------|
+| Signature help         | Unimplemented                                                                            | `textDocument/signatureHelp`                        |
+| Jump to declaration    | Unclear if useful                                                                        | `textDocument/declaration`                          |
+| Jump to implementation | Unclear if useful                                                                        | `textDocument/implementation`                       |
+| Renaming               | [Parital implementation](https://github.com/haskell/haskell-language-server/issues/2193) | `textDocument/rename`, `textDocument/prepareRename` |
+| Folding                | Unimplemented                                                                            | `textDocument/foldingRange`                         |
+| Selection range        | Unimplemented                                                                            | `textDocument/selectionRange`                       |
+| Semantic tokens        | Unimplemented                                                                            | `textDocument/semanticTokens`                       |
+| Linked editing         | Unimplemented                                                                            | `textDocument/linkedEditingRange`                   |
+| Document links         | Unimplemented                                                                            | `textDocument/documentLink`                         |
+| Document color         | Unclear if useful                                                                        | `textDocument/documentColor`                        |
+| Color presentation     | Unclear if useful                                                                        | `textDocument/colorPresentation`                    |
+| Monikers               | Unclear if useful                                                                        | `textDocument/moniker`                              |
diff --git a/docs/what-is-hls.md b/docs/what-is-hls.md
@@ -33,6 +33,7 @@ Here are a few pieces of jargon that you may come across in the HLS docs or when
 - *Completion item*: An item that can be inserted into the text, including its metadata.
 - *Diagnostic*: Any information about the project that is shown in the editor, including errors, warnings, and hints from tools such as hlint.
 - *Semantic highlighting*: Special syntax highlighting performed by the server.
+- *Method*: A LSP method is a function in the LSP protocol that the client can invoke to perform some action, e.g. ask for completions at a point.
 
 ## haskell-language-server
 
