Sir4ur0n/doc/cleanup hie (#2311)

* Update documentation on using HIE with HLS

Followup of #1230

* Cleanup some documentation links that are not visible with inline code

Author: sir4ur0n

Diff for: docs/configuration.md

@@ -21,14 +21,14 @@ For example, there are protocol methods for highlighting matching identifiers th
 This is a capability which any server can implement, so the client can decide generically whether to ask the server to do it or not.
 So your editor can provide a setting to turn this on or off globally, for any language server you might use.
 
-Settings like this are typically provided by the generic LSP client support for your editor, for example in Emacs by [`lsp-mode`](https://github.com/emacs-lsp/lsp-mode).
+Settings like this are typically provided by the generic LSP client support for your editor, for example in Emacs by [lsp-mode](https://github.com/emacs-lsp/lsp-mode).
 
 ### Generic editor options
 
 Your editor may provide some settings that affect how the information from the language server is used.
 For example, whether popups are shown, or whether code lenses appear by default.
 
-Settings like this are typically provided by the generic LSP client support for your editor, for example in Emacs by [`lsp-mode`](https://github.com/emacs-lsp/lsp-mode).
+Settings like this are typically provided by the generic LSP client support for your editor, for example in Emacs by [lsp-mode](https://github.com/emacs-lsp/lsp-mode).
 
 ### Language-specific server options
 
@@ -48,7 +48,7 @@ Here is a list of the additional settings currently supported by `haskell-langua
 - Hlint (`haskell.hlintOn`, default true): whether to enable Hlint support. *Deprecated* as it is equivalen to `haskell.plugin.hlint.globalOn`
 - Max completions (`haskell.maxCompletions`, default 40): maximum number of completions sent to the LSP client.
 - Check project (`haskell.checkProject`, default true): whether to typecheck the entire project on load. As it is activated by default could drive to bad perfomance in large projects.
-- Check parents (`haskell.checkParents`, default `CheckOnSaveAndClose`): when to typecheck reverse dependencies of a file; one of `NeverCheck`, `CheckOnClose`, `CheckOnSaveAndClose`, or `AlwaysCheck`. 
+- Check parents (`haskell.checkParents`, default `CheckOnSaveAndClose`): when to typecheck reverse dependencies of a file; one of `NeverCheck`, `CheckOnClose`, `CheckOnSaveAndClose`, or `AlwaysCheck`.
 
 #### Generic plugin configuration
 
@@ -57,7 +57,7 @@ Plugins have a generic config to control their behaviour. The schema of such con
 - `haskell.plugin.${pluginName}.globalOn`: usually with default true. Whether the plugin is enabled at runtime or it is not. That is the option you might use if you want to disable completely a plugin.
   - Actual plugin names are: `ghcide-code-actions-fill-holes`, `ghcide-completions`, `ghcide-hover-and-symbols`, `ghcide-type-lenses`, `ghcide-code-actions-type-signatures`, `ghcide-code-actions-bindings`, `ghcide-code-actions-imports-exports`, `eval`, `moduleName`, `pragmas`, `refineImports`, `importLens`, `class`, `tactics` (aka wingman), `hlint`, `haddockComments`, `retrie`, `splice`.
   - So to disable the import lens with an explicit list of module definitions you could set `haskell.plugin.importLens.globalOn: false`
-- `haskell.plugin.${pluginName}.${lspCapability}On`: usually with default true. Whether a concrete plugin capability is enabled. 
+- `haskell.plugin.${pluginName}.${lspCapability}On`: usually with default true. Whether a concrete plugin capability is enabled.
   - Capabilities are the different ways a lsp server can interact with the editor. The current available capabilities of the server are: `callHierarchy`, `codeActions`, `codeLens`, `diagnostics`, `hover`, `symbols`, `completion`, `rename`.
   - Note that usually plugins don't provide all capabilities but some of them or even only one.
   - So to disable code changes suggestions from the `hlint` plugin (but no diagnostics) you could set `haskell.plugin.hlint.codeActionsOn: false`
@@ -78,7 +78,7 @@ Plugins have a generic config to control their behaviour. The schema of such con
 This reference of configuration can be outdated at any time but we can query the `haskell-server-executable` about what configuration is effectively used:
 - `haskell-language-server generate-default-config`: will print the json configuration with all default values. It can be used as template to modify it.
 - `haskell-language-server vscode-extension-schema`: will print a json schema used to setup the haskell vscode extension. But it is useful to see what range of values can an option take and a description about it.
-  
+
 Settings like this are typically provided by the language-specific LSP client support for your editor, for example in Emacs by `lsp-haskell`.
 
 ### Client options
@@ -90,11 +90,11 @@ Settings like this are typically be provided by the language-specific LSP client
 ## Configuring your project build
 
 `haskell-language-server` has to compile your project in order to give you diagnostics, which means that it needs to know how to do so.
-This is handled by the [`hie-bios`](https://github.com/mpickering/hie-bios) project.
+This is handled by the [hie-bios](https://github.com/mpickering/hie-bios) project.
 
-**For a full explanation of how `hie-bios` determines the project build configuration, and how to configure it manually, refer to the [`hie-bios` README](https://github.com/mpickering/hie-bios/blob/master/README.md).**
+**For a full explanation of how `hie-bios` determines the project build configuration, and how to configure it manually, refer to the [hie-bios README](https://github.com/mpickering/hie-bios/blob/master/README.md).**
 
-At the moment, `haskell-language-server` has support to automatically detect your project build configuration to handle most use cases. 
+At the moment, `haskell-language-server` has support to automatically detect your project build configuration to handle most use cases.
 
 *So using a explicit `hie.yaml` file will not likely fix your ide setup*. It will do it almost only if you see an error like `Multi Cradle: No prefixes matched`
 
@@ -104,7 +104,7 @@ For that you need to know what *components* your project has, and the path assoc
 So you will need some knowledge about
 [stack](https://docs.haskellstack.org/en/stable/build_command/#components) or [cabal](https://cabal.readthedocs.io/en/latest/cabal-commands.html?#cabal-v2-build) components.
 
-You also can use [this utility](https://github.com/Avi-D-coder/implicit-hie) to automatically generate `hie.yaml` files for
+You also can use [implicit-hie](https://github.com/Avi-D-coder/implicit-hie) to automatically generate `hie.yaml` files for
 the most common stack and cabal configurations
 
 For example, to state that you want to use `stack` then the configuration file
@@ -351,7 +351,7 @@ it may also be helpful to also specify root markers:
 let g:LanguageClient_rootMarkers = ['*.cabal', 'stack.yaml']
 ```
 
-Further configuration can be done by pointing the [`g:LanguageClient_settingsPath`](https://github.com/autozimu/LanguageClient-neovim/blob/0e5c9546bfddbaa2b01e5056389c25aefc8bf989/doc/LanguageClient.txt#L221)
+Further configuration can be done by pointing the `g:LanguageClient_settingsPath` [option](https://github.com/autozimu/LanguageClient-neovim/blob/0e5c9546bfddbaa2b01e5056389c25aefc8bf989/doc/LanguageClient.txt#L221)
 variable to the file in which you want to keep your LSP settings.
 
 ### Atom

Diff for: docs/contributing/contributing.md

@@ -10,7 +10,7 @@ The Haskell tooling dream is near, we need your help!
 - Join the [haskell-tooling channel](https://matrix.to/#/#haskell-tooling:matrix.org) in [matrix](https://matrix.org/).
 - Visit [the project GitHub repo](https://github.com/haskell/haskell-language-server) to view the source code, or open issues or pull requests.
 
-## Building haskell-language-server
+## Building
 
 Clone the repository:
 ```shell
@@ -19,26 +19,18 @@ $ git clone https://github.com/haskell/haskell-language-server
 
 The project can then be built with both `cabal build` and `stack build`.
 
-haskell-language-server can also be used with itself. We provide preset samples of `hie.yaml` for Cabal and Stack.
-
-Note: the `./install/` folder is not directly tied to the project so it has dedicated `./install/hie.yaml.[cbl|stack]`
-templates.
-
 ### Using Cabal
 
 ```shell
-$ cp hie-cabal.yaml hie.yaml
-$ cp install/hie-cabal.yaml install/hie.yaml
+# If you have not run `cabal update` in a while
+$ cabal update
+# Then
+$ cabal build
 ```
 
 ### Using Stack
 
 ```shell
-$ cp hie-stack.yaml hie.yaml
-$ cp install/hie-stack.yaml install/hie.yaml
-$ cp ghcide/hie-stack.yaml ghcide/hie.yaml
-$ stack build --test --no-run-tests
-$ cd install
 $ stack build
 ```
 
@@ -119,26 +111,39 @@ An alternative, which only recompiles when tests (or dependencies) change:
 $ cabal run haskell-language-server:func-test -- -p "hlint enables"
 ```
 
-### Test your hacked HLS in your editor
+## Using HLS on HLS code
+
+[HLS project configuration guidelines](../configuration.md#configuring-your-project-build) also apply to the HLS project itself.
+
+Note: HLS implicitly detects HLS codebase as a Stack project (see [hie-bios implicit configuration documentation](https://github.com/haskell/hie-bios/blob/master/README.md#implicit-configuration)).
+If you want HLS to use Cabal, you need to create an `hie.yaml` file:
+```yaml
+cradle:
+  cabal:
+```
+
+Also note that the `install/` subdirectory is a different project, so if you want to work on this part of the code, you may also have to create an `install/hie.yaml` file.
 
+### Manually testing your hacked HLS
 If you want to test HLS while hacking on it, follow the steps below.
 
 To do once:
 
-- Open some codebase on which you want to test your hacked HLS in your favorite editor
+- Open some codebase on which you want to test your hacked HLS in your favorite editor (it can also be HLS codebase itself: see previous section for configuration)
 - Configure this editor to use your custom HLS executable
   - With Cabal:
     - On Unix systems: `cabal exec which haskell-language-server`
     - On Windows: `cabal exec where haskell-language-server`
   - With Stack: `$(stack path --dist-dir)/build/haskell-language-server/haskell-language-server`
 
-To do every time you changed code and want to test it:
+To do every time you change HLS code and want to test it:
 
 - Build HLS
   - With Cabal: `cabal build exe:haskell-language-server`
   - With Stack: `stack build haskell-language-server:exe:haskell-language-server`
 - Restart HLS
   - With VS Code: `Haskell: Restart Haskell LSP Server`
+  - With Emacs: `lsp-workspace-restart`
 
 ## Style guidelines