Merge remote-tracking branch 'origin/ghc-8.10' into ghc-9.0

.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: CI
+
+# Trigger the workflow on push or pull request, but only for the master branch
+on:
+  pull_request:
+  push:
+    branches: ["ghc-8.10"]
+
+jobs:
+  cabal:
+    name: ${{ matrix.os }} / ghc ${{ matrix.ghc }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        cabal: ["3.2"]
+        ghc:
+          - "8.10.1"
+          - "8.10.2"
+
+    steps:
+    - uses: actions/checkout@v2
+      if: github.event.action == 'opened' || github.event.action == 'synchronize' || github.event.ref == 'refs/heads/ghc-8.10'
+
+    - uses: actions/[email protected]
+      id: setup-haskell-cabal
+      name: Setup Haskell
+      with:
+        ghc-version: ${{ matrix.ghc }}
+        cabal-version: ${{ matrix.cabal }}
+
+    - name: Freeze
+      run: |
+        cabal freeze
+
+    - uses: actions/cache@v1
+      name: Cache ~/.cabal/store
+      with:
+        path: ${{ steps.setup-haskell-cabal.outputs.cabal-store }}
+        key: ${{ runner.os }}-${{ matrix.ghc }}-${{ hashFiles('cabal.project.freeze') }}
+
+    - name: Build
+      run: |
+        cabal configure --enable-tests --enable-benchmarks --test-show-details=direct
+        cabal build all
+
+    - name: Test
+      run: |
+        cabal test all

.gitignore

@@ -8,6 +8,12 @@
 /latex-test/out/
 /hoogle-test/out/
 
+*.o
+*.hi
+*.dyn_o
+*.dyn_hi
+*.hp
+
 /doc/haddock
 /doc/haddock.ps
 /doc/haddock.pdf

CHANGES.md

@@ -1,6 +1,13 @@
-## Changes in TBA
+## Changes in 2.24.0
 
- * NewOcean is the new default theme (#721, #782, #949)
+ * Reify oversaturated data family instances correctly (#1103)
+
+ * Removed the majority of Haddock's possible `panic` routes through
+   the TTG refactor to make extension variants empty
+
+## Changes in 2.23.0
+
+ * "Linuwial" is the new default theme (#721, #782, #949)
 
  * Fix style switcher (enabled by `--built-in-themes`) (#949)
 
@@ -12,6 +19,25 @@
  * The hyperlinker backend lexer is now more incremental, faster, and
    more memory efficient (#977)
 
+ * Add an "Instances" menu item to the HTML backend for controlling
+   settings related to expanding/collapsing instances (#1007)
+
+ * Improved identifier links including value/type namespaces, and
+   hyperlinking of parenthesized/backticked identifiers
+
+ * Substantial bugfixes for converting `TyThing` back into source
+   declarations (#1003, #1005, #1022, #1020)
+
+ * `--show-interface` now outputs to stdout (instead of stderr)
+
+ * Render associated type defaults and also improve rendering of
+   default method signatures
+
+ * Many fixes to the LaTeX backend, mostly focused on not crashing
+   as well as generating LaTeX source that compiles
+
+ * More flexible parsing of the module header
+
 ## Changes in version 2.22.0
 
  * Make `--package-version` optional for `--hoogle` (#899)

README.md

@@ -1,68 +1,63 @@
-# Haddock, a Haskell Documentation Tool [![Build Status](https://travis-ci.org/haskell/haddock.svg?branch=ghc-head)](https://travis-ci.org/haskell/haddock)
-
-
-## About haddock
-
-See [Description on Hackage](https://hackage.haskell.org/package/haddock).
-
-## Source code documentation
-
-Full documentation can be found in the `doc/` subdirectory, in
-[reStructedText format](http://www.sphinx-doc.org/en/stable/rest.html)
-format.
+# Haddock [![CI][CI badge]][CI page] [![Hackage][Hackage badge]][Hackage page]
 
+Haddock is the standard tool for generating documentation from Haskell code.
+Full documentation about Haddock itself can be found in the `doc/` subdirectory,
+in [reStructedText format][ReST] format.
 
 ## Project overview
 
 This project consists of three packages:
 
-* haddock
-* haddock-api
-* haddock-library
-
-### haddock
-
-The haddock package provides the `haddock` executable. It is implemented as a
-tiny wrapper around haddock-api's `Documentation.Haddock.haddock` function.
+ * `haddock`: provides the `haddock` executable. It is implemented as a tiny
+    wrapper around `haddock-api`'s `Documentation.Haddock.haddock` function.
 
-### haddock-api
-
-haddock-api contains the program logic of the `haddock` tool. [The haddocks for
-the `Documentation.Haddock` module](http://hackage.haskell.org/package/haddock-api-2.19.0.1/docs/Documentation-Haddock.html)
-offer a good overview of haddock-api's functionality.
-
-### haddock-library
-
-haddock-library is concerned with the parsing and processing of the Haddock
-markup language.
+ * `haddock-api`: contains the program logic of the `haddock` tool.
+   [The haddocks for the `Documentation.Haddock` module][Documentation.Haddock]
+   offer a good overview of the functionality.
 
+ * `haddock-library`: is concerned with the parsing and processing of the
+   Haddock markup language. Unlike the other packages, it is expected to build
+   on a fairly wide range of GHC versions.
 
 ## Contributing
 
-Please create issues when you have any problems and pull requests if you have some code.
+Please create issues when you have any problems and pull requests if you have
+some code.
 
 ## Hacking
 
-To get started you'll need a latest GHC release installed.
+To get started you'll need the latest GHC release installed.
 
 Clone the repository:
 
 ```bash
-  git clone https://github.com/haskell/haddock.git
-  cd haddock
+git clone https://github.com/haskell/haddock.git
+cd haddock
 ```
 
 and then proceed using your favourite build tool.
 
-#### Using [`cabal new-build`](http://cabal.readthedocs.io/en/latest/nix-local-build-overview.html)
+Note: before building `haddock`, you need to build the subprojects
+`haddock-library` and `haddock-api`, in this order!
+The `cabal v2-build` takes care of this automatically.
+
+#### Using [`cabal v2-build`][cabal v2]
 
 ```bash
-cabal new-build -w ghc-head
-# build & run the test suite
-cabal new-test -w ghc-head all
+cabal v2-build -w ghc-8.10.1
+cabal v2-test -w ghc-8.10.1 all
 ```
 
-#### Using Cabal sandboxes
+#### Using `stack`
+
+```bash
+stack init
+stack build
+export HADDOCK_PATH="$(stack exec which haddock)"
+stack test
+```
+
+#### Using Cabal sandboxes (deprecated)
 
 ```bash
 cabal sandbox init
@@ -78,29 +73,29 @@ export HADDOCK_PATH="dist/build/haddock/haddock"
 cabal test
 ```
 
-#### Using Stack
-
-```bash
-stack init
-stack install
-# run the test suite
-export HADDOCK_PATH="$HOME/.local/bin/haddock"
-stack test
-```
-
 ### Git Branches
 
-If you're a GHC developer and want to update Haddock to work with your
-changes, you should be working on `ghc-head` branch.
-See instructions at
-https://ghc.haskell.org/trac/ghc/wiki/WorkingConventions/Git/Submodules
+If you're a GHC developer and want to update Haddock to work with your changes,
+you should be working on the `ghc-head` branch. See instructions at
+<https://gitlab.haskell.org/ghc/ghc/-/wikis/working-conventions/git/submodules>
 for an example workflow.
 
-### Updating `html-test`
+### Updating golden testsuite outputs
 
-When accepting any changes in the output of `html-test`, it is important
-to use the `--haddock-path` option. For example:
+If you've changed Haddock's output, you will probably need to accept the new
+output of Haddock's golden test suites (`html-test`, `latex-test`,
+`hoogle-test`, and `hypsrc-test`). This can be done by passing the `--accept`
+argument to these test suites. With a new enough version of `cabal-install`:
 
 ```
-cabal new-run -- html-test --haddock-path $(find dist-newstyle/ -executable -type f -name haddock) --accept
+cabal v2-test html-test latex-test hoogle-test hypsrc-test \
+  --test-option='--accept'
 ```
+
+[CI page]: https://travis-ci.org/haskell/haddock
+[CI badge]: https://travis-ci.org/haskell/haddock.svg?branch=ghc-8.10
+[Hackage page]: https://hackage.haskell.org/package/haddock
+[Hackage badge]: https://img.shields.io/hackage/v/haddock.svg
+[ReST]: http://www.sphinx-doc.org/en/stable/rest.html
+[Documentation.Haddock]: http://hackage.haskell.org/package/haddock-api/docs/Documentation-Haddock.html
+[cabal v2]: http://cabal.readthedocs.io/en/latest/nix-local-build-overview.html