Merge pull request #491 from haskell/jneira/revamp-readme

Reorganize README

Author: jneira

README.md

@@ -2,46 +2,29 @@
 
 [![vsmarketplacebadge](https://vsmarketplacebadge.apphb.com/version/haskell.haskell.svg)](https://marketplace.visualstudio.com/items?itemName=haskell.haskell)
 
-This extension adds language support for [Haskell](https://haskell.org), powered by the [Haskell Language Server](https://github.com/haskell/haskell-language-server).
+This extension adds language support for [Haskell](https://haskell.org), powered by the [Haskell Language Server](https://github.com/haskell/haskell-language-server).  
+As almost all features are provided by the server you might find interesting read its [documentation](https://haskell-language-server.readthedocs.io).
 
 ## Features
 
+You can watch demos for some of these features [here](https://haskell-language-server.readthedocs.io/en/latest/features.html#demos).
+
 - Warning and error diagnostics from GHC
-- Type information and documentation on hover
-- Jump to definition
+- 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
 - Show documentation and sources in hackage
-- Formatting via Brittany, Floskell, Fourmolu, Ormolu or Stylish Haskell
+- 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)
 - [Multi-root workspace](https://code.visualstudio.com/docs/editor/multi-root-workspaces) support
-- Code evaluation (Haskell Language Server), see ([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)
-
-- Integration with [retrie](https://hackage.haskell.org/package/retrie)
-
-  ![Retrie Demo](https://i.imgur.com/Ev7B87k.gif)
-
-- Code lenses for explicit import lists
-
-  ![Imports code lens Demo](https://imgur.com/pX9kvY4.gif)
-
-- Generate functions from type signatures, and intelligently complete holes using [Wingman (tactics)](https://github.com/haskell/haskell-language-server/tree/master/plugins/hls-tactics-plugin)
-
-  ![Wingman Demo](https://user-images.githubusercontent.com/307223/92657198-3d4be400-f2a9-11ea-8ad3-f541c8eea891.gif)
-
-- Integration with [hlint](https://github.com/ndmitchell/hlint) to show diagnostics and apply hints via [apply-refact](https://github.com/mpickering/apply-refact)
-
-  ![Hlint Demo](https://user-images.githubusercontent.com/54035/110860028-8f9fa900-82bc-11eb-9fe5-6483d8bb95e6.gif)
-
-- Module name suggestions for insertion or correction
-
-  ![Module Name Demo](https://user-images.githubusercontent.com/54035/110860755-78ad8680-82bd-11eb-9845-9ea4b1cc1f76.gif)
-
-- Call hierarchy support
-
-  ![Call Hierarchy in VSCode](https://github.com/haskell/haskell-language-server/raw/2857eeece0398e1cd4b2ffb6069b05c4d2308b39/plugins/hls-call-hierarchy-plugin/call-hierarchy-in-vscode.gif)
+- [Code evaluation](https://haskell-language-server.readthedocs.io/en/latest/features.html#code-evaluation), see its [Tutorial](https://github.com/haskell/haskell-language-server/blob/master/plugins/hls-eval-plugin/README.md)
+- [Integration with](https://haskell-language-server.readthedocs.io/en/latest/features.html#retrie-integration) [retrie](https://hackage.haskell.org/package/retrie), a powerful, easy-to-use codemodding tool
+- [Code lenses for explicit import lists](https://haskell-language-server.readthedocs.io/en/latest/features.html#explicit-import-lists)
+- [Generate functions from type signatures, and intelligently complete holes using](https://haskell-language-server.readthedocs.io/en/latest/features.html#wingman) [Wingman (tactics)](https://github.com/haskell/haskell-language-server/tree/master/plugins/hls-tactics-plugin)
+- [Integration](https://haskell-language-server.readthedocs.io/en/latest/features.html#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](https://haskell-language-server.readthedocs.io/en/latest/features.html#module-names) for insertion or correction
+- [Call hierarchy support](https://haskell-language-server.readthedocs.io/en/latest/features.html#call-hierarchy)
 
 ## Requirements
 
@@ -52,6 +35,8 @@ This extension adds language support for [Haskell](https://haskell.org), powered
 
 ## Configuration options
 
+For a general picture about the server configuration, including the project setup, [you can consult the server documentation about the topic](https://haskell-language-server.readthedocs.io/en/latest/configuration.html).
+
 ### Path to server executable
 
 If your server is manually installed and not on your path, you can also manually set the path to the executable.
@@ -72,33 +57,6 @@ This supposes it could be used to execute arbitrary programs adding a `.vscode/s
 For this reason its scope will be changed to `machine` so users only will be able to change it globally.
 See #387 for more details.
 
-### Local documentation
-
-Haskell Language Server can display Haddock documentation on hover and completions if the project and
-its dependencies have been built with the `-haddock` GHC flag.
-
-- For cabal:
-
-  - Add to your global config file (e.g. `~/.cabal/config`):
-
-    ```yaml
-    program-default-options
-      ghc-options: -haddock
-    ```
-
-  - Or, for a single project, run `cabal configure --ghc-options=-haddock`
-
-- For stack, add to global `$STACK_ROOT\config.yaml`, or project's `stack.yaml`:
-
-  ```yaml
-  ghc-options:
-    '$everything': -haddock
-  ```
-
-  Note that this flag will cause compilation errors if a dependency contains invalid Haddock markup,
-  until GHC 9.0 which [will report warnings](https://gitlab.haskell.org/ghc/ghc/-/merge_requests/2377)
-  instead.
-
 ### Downloaded binaries
 
 This extension will download `haskell-language-server` binaries to a specific location depending on your system. If you find yourself running out of disk space, you can try deleting old versions of language servers in this directory. The extension will redownload them, no strings attached.
@@ -129,7 +87,8 @@ These are the versions of GHC that there are binaries of `haskell-language-serve
 | 8.6.5                                                                            | ✓     | ✓     | ✓       |
 | 8.6.4                                                                            | ✓     | ✓     | ✓       |
 
-The exact list of binaries can be checked in the last release of haskell-language-server: <https://github.com/haskell/haskell-language-server/releases/latest>
+The exact list of binaries can be checked in the last release of haskell-language-server: <https://github.com/haskell/haskell-language-server/releases/latest>  
+You can check the current GHC versions support status and the policy followed for deprecations [here](https://haskell-language-server.readthedocs.io/en/latest/supported-versions.html).
 
 ## Using multi-root workspaces