Documentation: Imrpove "Contributing" (and amend Sphinx builders) (#4494)

* Documentation: Improve "Contributing"

Also fix some warnings when compiling the documentation with Sphinx.

* Documentation: Nix uses `make` to build documentation

Author: dschrempf

.readthedocs.yaml

@@ -1,6 +1,7 @@
 version: 2
 
 sphinx:
+  builder: "html"
   configuration: docs/conf.py
 
 build:

docs/Makefile

@@ -1,5 +1,4 @@
 # Minimal makefile for Sphinx documentation
-#
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
@@ -8,13 +7,7 @@ SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build
 
-# Put it first so that "make" without argument is like "make help".
-help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+.PHONY: Makefile
 
-.PHONY: help Makefile
-
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+html: Makefile
+	@$(SPHINXBUILD) -n -W "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/contributing/contributing.md

@@ -2,9 +2,9 @@
 
 The Haskell tooling dream is near, we need your help!
 
-## How to contact the haskell ide team
+## How to contact the Haskell Language Server (HLS) team
 
-- Join the [haskell-language-server channel](https://matrix.to/#/#haskell-language-server:matrix.org) in [matrix](https://matrix.org/) (primary communication channel).
+- Join the [haskell-language-server channel](https://matrix.to/#/#haskell-language-server:matrix.org) on [matrix](https://matrix.org/) (primary communication channel).
 - Join [our IRC channel](https://web.libera.chat/?channels=#haskell-language-server) at `#haskell-language-server` on [`libera`](https://libera.chat/) (secondary communication channel - all messages in this IRC channel are automatically bridged to the Matrix channel).
 - Visit [the project GitHub repo](https://github.com/haskell/haskell-language-server) to view the source code, or open issues or pull requests.
 
@@ -17,7 +17,7 @@ $ git clone https://github.com/haskell/haskell-language-server
 
 The project can then be built with both `cabal build` and `stack build`.
 
-### Using Cabal
+### Building with Cabal
 
 ```shell
 # If you have not run `cabal update` in a while
@@ -26,15 +26,15 @@ $ cabal update
 $ cabal build
 ```
 
-### Using Stack
+### Building with Stack
 
 ```shell
 $ stack build
 ```
 
-### Using Nix
+### Building with Nix
 
-The instructions below show how to set up a Cachix binary cache and open a nix shell for local development.
+The instructions below show how to set up a Cachix binary cache and open a Nix shell for local development.
 
 ```shell
 $ cachix use haskell-language-server
@@ -45,19 +45,19 @@ $ cabal build
 
 #### Flakes support
 
-If you are using nix 2.4 style command (enabled by `experimental-features = nix-command`),
+If you are using Nix 2.4 style commands (enabled by `experimental-features = nix-command`),
 you can use `nix develop` instead of `nix-shell` to enter the development shell. To enter the shell with specific GHC versions:
 
-* `nix develop` - default GHC version
-* `nix develop .#shell-ghc90` - GHC 9.0.1 (substitute GHC version as appropriate)
+* `nix develop` - default GHC version,
+* `nix develop .#shell-ghc90` - GHC 9.0.1 (substitute GHC version as appropriate).
 
-If you are looking for a Nix expression to create haskell-language-server binaries, see https://github.com/haskell/haskell-language-server/issues/122
+If you are looking for a Nix expression to create `haskell-language-server` binaries, see https://github.com/haskell/haskell-language-server/issues/122
 
 ## Testing
 
 The tests make use of the [Tasty](https://github.com/feuerbach/tasty) test framework.
 
-There are two test suites in the main haskell-language-server package, functional tests, and wrapper tests.
+There are two test suites in the main `haskell-language-server` package, functional tests, and wrapper tests.
 Some of the wrapper tests expect `stack` to be present on the system, or else they fail.
 Other project packages, like the core library or plugins, can have their own test suite.
 
@@ -92,7 +92,7 @@ $ cabal test hls-refactor-plugin-tests
 Running a subset of tests
 
 Tasty supports providing
-[Patterns](https://github.com/feuerbach/tasty#patterns) as command
+[patterns](https://github.com/feuerbach/tasty#patterns) as command
 line arguments, to select the specific tests to run.
 
 ```bash
@@ -126,7 +126,7 @@ If you want to test HLS while hacking on it (you can even test it on HLS codebas
 3. (Every time you change the HLS code) Rebuild HLS
 4. (Every time you change the HLS code) Restart the LSP workspace
 
-### Find the path to the hacked HLS you build
+### Find the path to your HLS build
 Note that unless you change the GHC version or the HLS version between builds, the path should remain the same, this is why you need to set it only once.
 
 #### Using Cabal
@@ -145,9 +145,9 @@ $ echo $(pwd)/$(stack path --dist-dir)/build/haskell-language-server/haskell-lan
 <some long path>/haskell-language-server
 ```
 
-### Configure your editor to use it
+### Configuring your editor to use your HLS build
 
-#### VS Code
+#### Configuring VS Code
 When using VS Code you can set up each project to use a specific HLS executable:
 
 - If it doesn't already exist in your project directory, create a directory called `.vscode`.
@@ -158,7 +158,7 @@ When using VS Code you can set up each project to use a specific HLS executable:
 }
 ```
 
-#### Emacs
+#### Configuring Emacs
 There are several ways to configure the HLS server path:
 - `M-x customize-group<RET>lsp-haskell<RET>Lsp Haskell Server Path`
 - Evaluate `(setq lsp-haskell-server-path "/path/to/your/hacked/haskell-language-server")`
@@ -180,73 +180,66 @@ There are several ways to configure the HLS server path:
 
 The project includes a [`.editorconfig`](https://editorconfig.org) [file](https://github.com/haskell/haskell-language-server/blob/master/.editorconfig) with the editor basic settings used by the project.
 However, most editors will need some action to honour those settings automatically.
-For example vscode needs to have installed a specific [extension](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig).
+For example VS Code needs to have installed a specific [extension](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig).
 Please, try to follow those basic settings to keep the codebase as uniform as possible.
 
 ### Formatter pre-commit hook
 
-We are using [pre-commit](https://pre-commit.com/) to configure git pre-commit hook for formatting. Although it is possible to run formatting manually, we recommend you to use it to set pre-commit hook as our CI checks pre-commit hook is applied or not.
+We are using [pre-commit](https://pre-commit.com/) to configure the git pre-commit hook for formatting. Although it is possible to format code manually, we recommend you to use the pre-commit hook as our CI checks if the hook was applied or not.
 
-If you are using Nix or Gitpod, pre-commit hook is automatically installed. Otherwise, follow instructions on
-[https://pre-commit.com/](https://pre-commit.com/) to install the `pre-commit` tool, then run the following command:
+If you are using Nix or Gitpod, the pre-commit hook is automatically installed. Otherwise, follow the instructions on
+[https://pre-commit.com/](https://pre-commit.com/) to install the `pre-commit` tool. Then run the following command:
 
 ```sh
 pre-commit install
 ```
 
-#### Why some components are excluded from automatic formatting?
+#### Why are some components excluded from automatic formatting?
 
-- `test/testdata` and `test/data` are there as we want to test formatting plugins.
-- `hie-compat` is there as we want to keep its code as close to GHC as possible.
+- `test/testdata` and `test/data` are excluded because we want to test formatting plugins.
+- `hie-compat` is excluded because we want to keep its code as close to GHC as possible.
 
-## Introduction tutorial
+## Plugin tutorial
 
-See the [tutorial](./plugin-tutorial.md) on writing a plugin in HLS.
+See the [tutorial on writing a plugin in HLS](./plugin-tutorial.md).
 
 ## Measuring, benchmarking and tracing
 
 ### Benchmarks
 
-If you are touching performance sensitive code, take the time to run a differential
-benchmark between HEAD and master using the benchHist script. This assumes that
-"master" points to the upstream master.
+If you are touching performance sensitive code, take the time to run a differential benchmark between `HEAD` and `origin/master` (see [bench/README](https://github.com/haskell/haskell-language-server/blob/master/bench/README.md)).
 
-Run the benchmarks with `cabal bench`.
-
-It should take around 25 minutes and the results will be stored in the `bench-results` folder. To interpret the results, see the comments in the `bench/Main.hs` module.
-
-More details in [bench/README](https://github.com/haskell/haskell-language-server/blob/master/bench/README.md)
+Run the benchmarks with `cabal bench`. The runtime is about 25 minutes and the results will be stored in the `bench-results` folder. To interpret the results, see the comments in the [bench/Main.hs](https://github.com/haskell/haskell-language-server/blob/master/bench/Main.hs) module.
 
 ### Tracing
 
-HLS records opentelemetry [eventlog traces](https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/runtime_control.html#rts-eventlog) via [opentelemetry](https://hackage.haskell.org/package/opentelemetry). To generate the traces, build with `-eventlog` and run with `+RTS -l`. To visualize the traces, install [Tracy](https://github.com/wolfpld/tracy) and use [eventlog-to-tracy](https://hackage.haskell.org/package/opentelemetry-extra) to open the generated eventlog.
+HLS records [eventlog traces](https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/runtime_control.html#rts-eventlog) via [opentelemetry](https://hackage.haskell.org/package/opentelemetry). To generate the traces, build with `-eventlog` and run with `+RTS -l`. To visualize the traces, install [Tracy](https://github.com/wolfpld/tracy) and use [eventlog-to-tracy](https://hackage.haskell.org/package/opentelemetry-extra) to open the generated eventlog.
 
 ## Adding support for a new editor
 
 Adding support for new editors is fairly easy if the editor already has good support for generic LSP-based extensions.
-In that case, there will likely be an editor-specific support system for this (like `lsp-mode` for Emacs).
-This will typically provide instructions for how to support new languages.
+In that case, there will likely be an editor-specific support system (e.g., `lsp-mode` for Emacs).
+The support system will typically provide instructions for how to add support for new languages.
 
-In some cases you may need to write a small bit of additional client support, or expose a way for the user to set the server's [configuration options](../configuration.md#configuring-haskell-language-server) and
-for them to configure how the server is started.
+In some cases you may need to write a small bit of additional client support, or expose a way for the user to set the server's [configuration options](../configuration.md#configuring-haskell-language-server) and for them to configure how the server is started.
 
-## Building the docs
+## Building the documentation
 
-The docs are built with [Sphinx](https://www.sphinx-doc.org/en/master/) and [ReadTheDocs](https://docs.readthedocs.io/en/stable/index.html), the documentation for both is helpful.
+The documentation is built with [Sphinx](https://www.sphinx-doc.org/en/master/) and [ReadTheDocs](https://docs.readthedocs.io/en/stable/index.html), the documentation of both is helpful.
 
-To build the docs you need to install some Python prerequisites. You can either `pip install -r docs/requirements.txt`, or simply enter a `nix-shell`.
+You need to install some Python prerequisites. You can either `pip install -r docs/requirements.txt`, or simply enter a `nix-shell`.
 
-Then to build and preview the docs:
+Then to build and preview the documentation:
 
 ```
 cd docs
 make html
 firefox _build/html/index.html
 ```
 
-Alternatively, you can build the entire thing as a Nix derivation from the flake with `nix build .#docs`.
+Alternatively, you can build the documentation as a Nix derivation from the Flake with `nix build .#docs`.
 
-The docs are also built and previewed on every PR, so you can check them from the PR status.
+The documentation is also built and previewed on every PR, so you can check them from the PR status.
 
 ## Working on code actions
 
@@ -255,8 +248,8 @@ To make HLS easier to maintain, please follow these design guidelines when addin
 1. Prefer `ghc-exactprint` to manual text parsing.
 2. Prefer `ghc-exactprint` to manual code generation.
 3. Code generating actions should not try to format the generated code. Assume that the user is also leveraging HLS for automated code formatting.
-4. Put new code actions in their own plugin unless they are very closely aligned with an existing ghcide code action.
+4. Put new code actions in their own plugin unless they are very closely aligned with an existing code action.
 
 ## Sponsorship
 
-If you want to contribute financially you can do so via [open-collective](https://opencollective.com/haskell-language-server). In the past the funding has been used to sponsor [summer student projects](https://mpickering.github.io/ide/posts/2021-07-22-summer-of-hls.html).
+If you want to contribute financially, you can do so via [open-collective](https://opencollective.com/haskell-language-server). In the past, the funding was used to sponsor [summer student projects](https://mpickering.github.io/ide/posts/2021-07-22-summer-of-hls.html).

docs/index.rst

@@ -1,7 +1,7 @@
 haskell-language-server
 =======================
 
-Official Haskell Language Server implementation. :ref:`Read more<What is haskell-language-server?>`.
+Official Haskell Language Server implementation. :ref:`Read more<What is the Haskell Language Server?>`.
 
 .. toctree::
    :maxdepth: 2

docs/what-is-hls.md

@@ -1,6 +1,6 @@
-# What is haskell-language-server?
+# What is the Haskell Language Server?
 
-The `haskell-language-server` (HLS) project is an implementation of a server (a "language server") for the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP).
+The Haskell Language Server (HLS) is an implementation of a server (a "language server") for the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP).
 A language server talks to a client (typically an editor), which can ask the server to perform various operations, such as reporting errors or providing code completions.
 The advantage of this system is that clients and servers can interoperate more easily so long as they all speak the LSP protocol.
 In the case of HLS, that means that it can be used with many different editors, since editor support for the LSP protocol is now widespread.
@@ -35,7 +35,7 @@ Here are a few pieces of jargon that you may come across in the HLS docs or when
 - *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
+## Haskell Language Server
 
 ### HLS and its wrapper
 
@@ -51,7 +51,7 @@ Plugins can also be disabled independently to allow users to customize the behav
 
 These plugins all (currently) live in the HLS repository and are developed in tandem with the core HLS functionality.
 
-See the [configuration page](./configuration.md#generic-plugin-configuration) for more on configuring plugins.
+See the [configuration page](./configuration.md#Generic plugin configuration) for more on configuring plugins.
 
 ### hie-bios
 

flake.nix

@@ -27,8 +27,10 @@
           name = "hls-docs";
           src = pkgs.lib.sourceFilesBySuffices ./. [ ".py" ".rst" ".md" ".png" ".gif" ".svg" ".cabal" ];
           buildInputs = [ pythonWithPackages ];
-          # -n gives warnings on missing link targets, -W makes warnings into errors
-          buildPhase = ''cd docs; sphinx-build -n -W . $out'';
+          buildPhase = ''
+            cd docs
+            make --makefile=${./docs/Makefile} html BUILDDIR=$out
+            '';
           dontInstall = true;
         };