.arcconfig

-{
-  "project.name"        : "haddock",
-  "repository.callsign" : "HADDOCK",
-  "phabricator.uri"     : "https://phabricator.haskell.org"
-}

.arclint

-{
-  "linters": {
-    "filename": {
-      "type": "filename"
-    },
-    "generated": {
-      "type": "generated"
-    },
-    "merge-conflict": {
-      "type": "merge-conflict"
-    },
-    "nolint": {
-      "type": "nolint"
-    },
-    "haskell": {
-      "type": "text",
-      "include": ["(\\.(l?hs(-boot)?|x|y\\.pp)(\\.in)?$)"],
-      "severity": {
-        "5": "disabled",
-        "2": "warning"
-      }
-    }
-  }
-}

.ghci

-:set --itest -idist/build -idist/build/autogen -packageghc -optP-include -optPdist/build/autogen/cabal_macros.h

.github/mergify.yml

+pull_request_rules:
+  # rebase+merge strategy
+  - actions:
+      queue:
+        name: default
+        # Merge into master with a merge commit
+        method: merge
+        # Update the pr branch with rebase, so the history is clean
+        update_method: rebase
+    name: Put pull requests in the rebase+merge queue
+    conditions:
+      - label=merge me
+      - '#approved-reviews-by>=1'
+  # merge+squash strategy
+  - actions:
+      queue:
+        name: default
+        method: squash
+        # both update methods get absorbed by the squash, so we use the most
+        # reliable
+        update_method: merge
+    name: Put pull requests in the squash+merge queue
+    conditions:
+      - label=squash+merge me
+      - '#approved-reviews-by>=1'
+
+queue_rules:
+  - name: default
+    conditions: []

.github/workflows/ci.yml

+name: CI
+
+# Trigger the workflow on push or pull request, but only for the master branch
+on:
+  pull_request:
+  push:
+    branches: ["ghc-head"]
+
+jobs:
+  cabal:
+    name: ${{ matrix.os }} / ghc ${{ matrix.ghc }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        cabal: ["3.6"]
+        ghc:
+          - "head"
+
+    steps:
+    - uses: actions/checkout@v2
+      if: github.event.action == 'opened' || github.event.action == 'synchronize' || github.event.ref == 'refs/heads/ghc-head'
+
+    - name: Install gmp and tinfo
+      run: |
+        sudo -- sh -c "apt-get update"
+        sudo -- sh -c "apt-get -y install libgmp-dev libtinfo-dev"
+
+    - uses: haskell/actions/setup@main
+      id: setup-haskell-cabal
+      name: Setup Haskell
+      with:
+        ghc-version: ${{ matrix.ghc }}
+        cabal-version: ${{ matrix.cabal }}
+
+    - name: Prepare environment
+      run: echo "$HOME/.ghcup/bin" >> $GITHUB_PATH
+
+    - name: Freeze
+      run: |
+        cabal freeze
+ 
+    - uses: actions/cache@v2
+      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 --test-show-details=direct --test-options="--haddock-stdout=/dev/stdout" all

.github/workflows/hlint-ci.yml

+name: hlint
+
+on:
+  pull_request:
+  push:
+
+jobs:
+  build:
+    name: hlint
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        submodules: true
+
+    - uses: rwe/actions-hlint-setup@v1
+      name: Set up HLint
+      with:
+        version: "3.4.1"
+
+    - uses: rwe/actions-hlint-run@v2
+      name: hlint
+      with:
+        path: '[ "haddock-library/", "haddock-api/", "haddock-test/", "hoogle-test/", "html-test/", "hypsrc-test/", "latex-test/" ]'
+        fail-on: suggestion
\ No newline at end of file

.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
@@ -29,3 +35,5 @@ cabal.project.local
 cabal.project.local~
 
 .stack-work/
+
+.hspec-failures

.hlint.yaml

+# Warnings currently triggered
+- ignore: {name: "Avoid lambda"} # 3 hints
+- ignore: {name: "Avoid lambda using `infix`"} # 5 hints
+- ignore: {name: "Eta reduce"} # 18 hints
+- ignore: {name: "Functor law"} # 3 hints
+- ignore: {name: "Fuse concatMap/map"} # 1 hint
+- ignore: {name: "Fuse foldr/map"} # 2 hints
+- ignore: {name: "Fuse mapM/map"} # 2 hints
+- ignore: {name: "Hoist not"} # 1 hint
+- ignore: {name: "Move brackets to avoid $"} # 7 hints
+- ignore: {name: "Move guards forward"} # 1 hint
+- ignore: {name: "Move map inside list comprehension"} # 2 hints
+- ignore: {name: "Redundant <$>"} # 3 hints
+- ignore: {name: "Redundant bracket"} # 44 hints
+- ignore: {name: "Redundant id"} # 1 hint
+- ignore: {name: "Redundant if"} # 3 hints
+- ignore: {name: "Redundant lambda"} # 2 hints
+- ignore: {name: "Redundant map"} # 3 hints
+- ignore: {name: "Redundant return"} # 1 hint
+- ignore: {name: "Replace case with fromMaybe"} # 2 hints
+- ignore: {name: "Replace case with maybe"} # 4 hints
+- ignore: {name: "Use $>"} # 4 hints
+- ignore: {name: "Use ++"} # 3 hints
+- ignore: {name: "Use :"} # 4 hints
+- ignore: {name: "Use <$>"} # 12 hints
+- ignore: {name: "Use <&>"} # 1 hint
+- ignore: {name: "Use <|>"} # 1 hint
+- ignore: {name: "Use =<<"} # 1 hint
+- ignore: {name: "Use all"} # 1 hint
+- ignore: {name: "Use bimap"} # 1 hint
+- ignore: {name: "Use camelCase"} # 31 hints
+- ignore: {name: "Use concatMap"} # 1 hint
+- ignore: {name: "Use const"} # 4 hints
+- ignore: {name: "Use fewer LANGUAGE pragmas"} # 1 hint
+- ignore: {name: "Use find"} # 1 hint
+- ignore: {name: "Use fmap"} # 12 hints
+- ignore: {name: "Use foldr"} # 1 hint
+- ignore: {name: "Use fromMaybe"} # 2 hints
+- ignore: {name: "Use infix"} # 3 hints
+- ignore: {name: "Use intercalate"} # 1 hint
+- ignore: {name: "Use isAsciiLower"} # 1 hint
+- ignore: {name: "Use isAsciiUpper"} # 1 hint
+- ignore: {name: "Use isDigit"} # 1 hint
+- ignore: {name: "Use lambda-case"} # 4 hints
+- ignore: {name: "Use let"} # 2 hints
+- ignore: {name: "Use list comprehension"} # 2 hints
+- ignore: {name: "Use list literal pattern"} # 1 hint
+- ignore: {name: "Use map once"} # 1 hint
+- ignore: {name: "Use maybe"} # 2 hints
+- ignore: {name: "Use newtype instead of data"} # 13 hints
+- ignore: {name: "Use notElem"} # 2 hints
+- ignore: {name: "Use print"} # 3 hints
+- ignore: {name: "Use record patterns"} # 5 hints
+- ignore: {name: "Use second"} # 3 hints
+- ignore: {name: "Use sortOn"} # 3 hints
+- ignore: {name: "Use tuple-section"} # 3 hints
+- ignore: {name: "Use unless"} # 1 hint
+- ignore: {name: "Use void"} # 1 hint
+# Ignore within modules where following hlint or adding an HLint annotation
+# would alter the expected test output.
+- ignore: {name: "Unused LANGUAGE pragma", within: [QuasiExpr, TH, Ticket112]}
+# Module names (not all unique) where CPP can be used
+- extensions:
+  - name: CPP
+    within:
+    - Bug1091
+    - CompatPrelude
+    - CPP
+    - Documentation.Haddock.Parser.UtilSpec
+    - Documentation.Haddock.Types
+    - Haddock
+    - Haddock.Config
+    - Haddock.Convert
+    - Haddock.Interface
+    - Haddock.Interface.Create
+    - Haddock.InterfaceFile
+    - Haddock.Types
+    - Haddock.Utils
+    - Haddock.Version
+    - Haddock.Backends.Xhtml
+    - Main
+    - Test.Haddock.Config

.travis.yml

-# This Travis job script has been generated by a script via
-#
-#   make_travis_yml_2.hs 'haddock.cabal'
-#
-# For more information, see https://github.com/hvr/multi-ghc-travis
-#
-language: c
-sudo: false
-
-git:
-  submodules: false  # whether to recursively clone submodules
-
-cache:
-  directories:
-    - $HOME/.cabal/packages
-    - $HOME/.cabal/store
-
-before_cache:
-  - rm -fv $HOME/.cabal/packages/hackage.haskell.org/build-reports.log
-  # remove files that are regenerated by 'cabal update'
-  - rm -fv $HOME/.cabal/packages/hackage.haskell.org/00-index.*
-  - rm -fv $HOME/.cabal/packages/hackage.haskell.org/*.json
-  - rm -fv $HOME/.cabal/packages/hackage.haskell.org/01-index.cache
-  - rm -fv $HOME/.cabal/packages/hackage.haskell.org/01-index.tar
-  - rm -fv $HOME/.cabal/packages/hackage.haskell.org/01-index.tar.idx
-
-  - rm -rfv $HOME/.cabal/packages/head.hackage
-
-matrix:
-  include:
-    - compiler: "ghc-head"
-      env: GHCHEAD=true
-    # env: TEST=--disable-tests BENCH=--disable-benchmarks
-      addons: {apt: {packages: [ghc-ppa-tools,cabal-install-head,ghc-head], sources: [hvr-ghc]}}
-
-before_install:
- - HC=${CC}
- - HCPKG=${HC/ghc/ghc-pkg}
- - unset CC
- - PATH=/opt/ghc/bin:/opt/ghc-ppa-tools/bin:$PATH
- - PKGNAME='haddock'
-
-install:
- - cabal --version
- - echo "$(${HC} --version) [$(${HC} --print-project-git-commit-id 2> /dev/null || echo '?')]"
- - BENCH=${BENCH---enable-benchmarks}
- - TEST=${TEST---enable-tests}
- - GHCHEAD=${GHCHEAD-false}
- - travis_retry cabal update -v
- - sed -i 's/^jobs:/-- jobs:/' ${HOME}/.cabal/config
- - rm -fv cabal.project.local
- - rm -f cabal.project.freeze
- # Overlay Hackage Package Index for GHC HEAD: https://github.com/hvr/head.hackage
- - |
-   if $GHCHEAD; then
-     sed -i 's/-- allow-newer: .*/allow-newer: *:base/' ${HOME}/.cabal/config
-     for pkg in $($HCPKG list --simple-output); do pkg=$(echo $pkg | sed 's/-[^-]*$//'); sed -i "s/allow-newer: /allow-newer: *:$pkg, /" ${HOME}/.cabal/config; done
-
-     echo 'repository head.hackage'                                                        >> ${HOME}/.cabal/config
-     echo '   url: http://head.hackage.haskell.org/'                                       >> ${HOME}/.cabal/config
-     echo '   secure: True'                                                                >> ${HOME}/.cabal/config
-     echo '   root-keys: 07c59cb65787dedfaef5bd5f987ceb5f7e5ebf88b904bbd4c5cbdeb2ff71b740' >> ${HOME}/.cabal/config
-     echo '              2e8555dde16ebd8df076f1a8ef13b8f14c66bad8eafefd7d9e37d0ed711821fb' >> ${HOME}/.cabal/config
-     echo '              8f79fd2389ab2967354407ec852cbe73f2e8635793ac446d09461ffb99527f6e' >> ${HOME}/.cabal/config
-     echo '   key-threshold: 3'                                                            >> ${HOME}/.cabal.config
-
-     grep -Ev -- '^\s*--' ${HOME}/.cabal/config | grep -Ev '^\s*$'
-
-     cabal new-update head.hackage -v
-   fi
- - travis_retry cabal new-build -w ${HC} ${TEST} ${BENCH} --dep -j2 --allow-newer --constraint 'setup.Cabal installed' all
- - travis_retry cabal new-build -w ${HC} --disable-tests --disable-benchmarks --dep -j2 --allow-newer --constraint 'setup.Cabal installed' all
-
-# Here starts the actual work to be performed for the package under test;
-# any command which exits with a non-zero exit code causes the build to fail.
-script:
- - if [ -f configure.ac ]; then autoreconf -i; fi
- - rm -rf dist/
- - cabal sdist # test that a source-distribution can be generated
- - cd dist/
- - SRCTAR=(${PKGNAME}-*.tar.gz)
- - SRC_BASENAME="${SRCTAR/%.tar.gz}"
- - tar -xvf "./$SRC_BASENAME.tar.gz"
- - cd "$SRC_BASENAME/"
-## from here on, CWD is inside the extracted source-tarball
- - rm -fv cabal.project.local
- # this builds all libraries and executables (without tests/benchmarks)
- - rm -f cabal.project.freeze
- - cabal new-build -w ${HC} --disable-tests --disable-benchmarks --allow-newer --constraint 'setup.Cabal installed'  all
- # this builds all libraries and executables (including tests/benchmarks)
- # - rm -rf ./dist-newstyle
-
- # build & run tests
- - cabal new-build -w ${HC} ${TEST} ${BENCH} --allow-newer --constraint 'setup.Cabal installed'   all
- - if [ "x$TEST" = "x--enable-tests" ]; then cabal new-test -w ${HC} ${TEST} --allow-newer --constraint 'setup.Cabal installed'  all; fi 
-
-# EOF

CHANGES.md

-## Changes in TBA
+## Changes in 2.28.0
+ * `hi-haddock` is integrated, which means docstrings are no longer extracted
+   through typchecked module results. Instead, docstrings are taken from Haskell
+   interface (`.hi`) files.
 
- * NewOcean is the new default theme (#721, #782, #949)
+ * Support qualified and unqualified names in `--ignore-link-symbol`.
+
+ * Add `--trace-args` flag which prints arguments to standard output. This is
+   useful for examining arguments passed when Haddock is invoked through `cabal
+   haddock`, as `cabal` uses temporary response files to pass arguments to
+   Haddock.
+
+ * Avoid recompilation due to changes in optimization flags.
+
+## Changes in 2.24.0
+
+ * 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 +33,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)

CODE_OF_CONDUCT.md

+# Conduct
+
+* We are committed to providing a friendly, safe and welcoming environment for all, regardless of level of experience,
+gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age,
+religion, nationality, or other similar characteristic.
+
+* Please avoid using overtly sexual aliases or other nicknames that might detract from a friendly, safe
+and welcoming environment for all.
+
+* Please be kind and courteous. There’s no need to be mean or rude.
+
+* Respect that people have differences of opinion and that every design or implementation choice carries a trade-off
+and numerous costs. There is seldom a right answer.
+
+* Please keep unstructured critique to a minimum. If you have solid ideas you want to experiment with,
+make a fork and see how it works.
+
+* We will exclude you from interaction if you insult, demean or harass anyone. That is not welcome behavior.
+We interpret the term “harassment” as including the definition in the [Citizen Code of Conduct][CCC];
+if you have any lack of clarity about what might be included in that concept, please read their definition.
+In particular, we don’t tolerate behavior that excludes people in socially marginalized groups.
+
+* Private harassment is also unacceptable. No matter who you are, if you feel you have been or are being harassed or
+made uncomfortable by a community member, please contact one of the maintainers or any of the
+Core Team immediately. Whether you’re a regular contributor or a newcomer,
+we care about making this community a safe place for you and we’ve got your back.
+
+* Likewise any spamming, trolling, flaming, baiting or other attention-stealing behavior is not welcome.
+
+_Adapted from the [Rust Lang][Rust CoC]'s code of conduct_
+
+[CCC]: https://github.com/stumpsyn/policies/blob/master/citizen_code_of_conduct.md
+[Rust CoC]: https://www.rust-lang.org/policies/code-of-conduct

CONTRIBUTING

-If you're filing an issue, here are the things which will help us a lot:
-
-* State your GHC version.
-
-* State your platform, OS and distribution if applicable.
-
-* State your cabal version if applicable.
-
-* Tell us how to replicate the problem. If we can't replicate it, we
-  can't fix it.
-
-* If the problem involves running Haddock on some source, please
-  include the sample on which we can replicate, the smaller/cleaner
-  the better. Include some images if you think it will help us.
-
-* Include any other info you think might be relevant (sandbox? unusual
-  setup?).

CONTRIBUTING.md

+# Contributing to Haddock
+
+Thank you for contributing to Haddock! Here is the information you will need in
+order to make your contribution
+
+## Code of Conduct
+
+We need you to read, acknowledge, and abide by our [Code of Conduct][CoC].
+
+## Reporting issues
+
+Please open a ticket if you get an unexpected behaviour from Haddock!  
+You should ideally include a [Short, Self Contained, Correct (Compilable), Example][SSCCE]
+in your ticket, so that the maintainers may easily reproduce your issue.
+
+Here is a list of things you should include in your ticket
+
+* Your GHC version.
+
+* Your platform, OS and distribution if applicable.
+
+* Your cabal version if applicable.
+
+* Include any other info you think might be relevant (sandbox? unusual setup?).
+
+## Hacking
+
+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 Branches
+
+If your patch consists of glue code and interface changes with GHC, please
+open a Pull Request targeting the `ghc-head` branch.
+
+Otherwise, for improvements to the documentation generator,
+please base your pull request on the current GHC version branch
+(`ghc-9.0` for instance). The PR will be forward-ported to `ghc-head`
+so that documentation built within GHC can benefit from it.
+
+### Building the packages
+
+#### Using `cabal`
+
+Requires cabal `>= 3.4` and GHC `== 9.4`:
+
+You can install the latest build of GHC via ghcup using this command:
+
+```bash
+ghcup install ghc -u "https://gitlab.haskell.org/ghc/ghc/-/jobs/artifacts/master/raw/ghc-x86_64-deb9-linux-integer-simple.tar.xz?job=validate-x86_64-linux-deb9-integer-simple" head
+```
+
+```bash
+cabal v2-build all --enable-tests
+cabal v2-test all
+```
+
+### Updating golden testsuite outputs
+
+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 v2-test html-test latex-test hoogle-test hypsrc-test \
+  --test-option='--accept'
+```
+
+
+[SSCCE]: http://sscce.org/
+[CoC]: ./CODE_OF_CONDUCT.md

LICENSE

-Copyright 2002-2010, Simon Marlow.  All rights reserved.
+Copyright (c) 2002-2010, Simon Marlow
+All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
+modification, are permitted provided that the following conditions are
+met:
 
-- Redistributions of source code must retain the above copyright notice,
-this list of conditions and the following disclaimer.
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
 
-- Redistributions in binary form must reproduce the above copyright notice,
-this list of conditions and the following disclaimer in the documentation
-and/or other materials provided with the distribution.
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the
+   distribution.
 
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS "AS IS" AND ANY
-EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
-PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE
-LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
-BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
-WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
-OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
-IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

-# 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 [reStructuredText][reST] format.
 
 ## Project overview
 
 This project consists of three packages:
 
-* haddock
-* haddock-api
-* haddock-library
-
-### haddock
+ * `haddock`: provides the `haddock` executable. It is implemented as a tiny
+    wrapper around `haddock-api`'s `Documentation.Haddock.haddock` function.
 
-The haddock package 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.
-
-## Hacking
-
-To get started you'll need a latest GHC release installed.
-
-Clone the repository:
-
-```bash
-  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)
-
-```bash
-cabal new-build -w ghc-head
-# build & run the test suite
-cabal new-test -w ghc-head all
-```
-
-#### Using Cabal sandboxes
-
-```bash
-cabal sandbox init
-cabal sandbox add-source haddock-library
-cabal sandbox add-source haddock-api
-cabal sandbox add-source haddock-test
-# adjust -j to the number of cores you want to use
-cabal install -j4 --dependencies-only --enable-tests
-cabal configure --enable-tests
-cabal build -j4
-# run the test suite
-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
-for an example workflow.
-
-### Updating `html-test`
+See [CONTRIBUTING.md](CONTRIBUTING.md) to see how to make contributions to the
+project.
 
-When accepting any changes in the output of `html-test`, it is important
-to use the `--haddock-path` option. For example:
 
-```
-cabal new-run -- html-test --haddock-path $(find dist-newstyle/ -executable -type f -name haddock) --accept
-```
+[CI page]: https://github.com/haskell/haddock/actions/workflows/ci.yml
+[CI badge]: https://github.com/haskell/haddock/actions/workflows/ci.yml/badge.svg
+[Hackage page]: https://hackage.haskell.org/package/haddock
+[Hackage badge]: https://img.shields.io/hackage/v/haddock.svg
+[reST]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
+[Documentation.Haddock]: http://hackage.haskell.org/package/haddock-api/docs/Documentation-Haddock.html
+[cabal v2]: https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html

STYLE

-
-See http://github.com/waern/haskell-style-guide
-

cabal.project

+with-compiler: ghc-9.7
+
 packages: ./
           ./haddock-api
           ./haddock-library
           ./haddock-test
+
+test-show-details: direct
+
+allow-newer:
+  ghc-paths:Cabal,
+  *:base,
+  *:ghc-prim,
+  tree-diff:time
+
+package haddock-library
+  tests: False
+
+package haddock-api
+  tests: False
+
+-- Pinning the index-state helps to make reasonably CI deterministic
+index-state: 2023-05-22T15:14:29Z

doc/cheatsheet/haddocks.md

@@ -109,14 +109,13 @@ definitions with "[thing]"
   Omit this module from the docs
 {-# OPTIONS_HADDOCK prune #-}
   Omit definitions without docs
-{-# OPTIONS_HADDOCK ignore-exports #-}
-  Treat this module as though all
-  top-level items are exported
 {-# OPTIONS_HADDOCK not-home #-}
   Do not treat this module as the
   "home" of identifiers it exports
 {-# OPTIONS_HADDOCK show-extensions #-}
   Show all enabled LANGUAGE extensions
+{-# OPTIONS_HADDOCK print-explicit-runtime-reps #-}
+  Show all `RuntimeRep` type variables
 ```
 
 # Grid tables

doc/common-errors.rst

+Common Errors
+=============
+
+``parse error on input ‘-- | xxx’``
+-----------------------------------
+
+This is probably caused by the ``-- | xxx`` comment not following a declaration. I.e. use ``-- xxx`` instead. See :ref:`top-level-declaration`.
+
+``parse error on input ‘-- $ xxx’``
+-----------------------------------
+
+You've probably commented out code like::
+
+  f x
+    $ xxx
+    
+``-- $`` is a special syntax for named chunks, see :ref:`named-chunks`. You can fix this by escaping the ``$``::
+
+  -- \$ xxx

doc/index.rst

@@ -12,6 +12,8 @@ Contents:
    intro
    invoking
    markup
+   common-errors
+   multi-components
 
 
 Indices and tables