aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAlec Theriault <alec.theriault@gmail.com>2020-03-26 19:40:38 -0400
committerAlec Theriault <alec.theriault@gmail.com>2020-03-26 20:10:53 -0400
commit8c6532636e6bd572455dfcf0b0d6e05f7033d110 (patch)
tree4accf545d6110a56589922d0ca4b6493defd3b00
parent7013f52cca144e8d5e4deb08913370f1819dbc68 (diff)
Update README
Removed some out of date links/info, added some more useful links. * badge to Hackage * update old trac link * `ghc-head` => `ghc-8.10` * `cabal new-*` is now `cabal v2-*` and it should Just Work * `--test-option='--accept'` is the way to accept testsuite output
-rw-r--r--README.md105
1 files changed, 48 insertions, 57 deletions
diff --git a/README.md b/README.md
index e421ef7e..4490a53e 100644
--- a/README.md
+++ b/README.md
@@ -1,68 +1,59 @@
-# 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)
+#### Using [`cabal v2-build`][cabal v2]
+
+```bash
+cabal v2-build -w ghc-8.10.1
+cabal v2-test -w ghc-8.10.1 all
+```
+
+#### Using `stack`
```bash
-cabal new-build -w ghc-head
-# build & run the test suite
-cabal new-test -w ghc-head all
+stack init
+stack build
+export HADDOCK_PATH="$(stack exec which haddock)"
+stack test
```
-#### Using Cabal sandboxes
+#### Using Cabal sandboxes (deprecated)
```bash
cabal sandbox init
@@ -78,29 +69,29 @@ export HADDOCK_PATH="dist/build/haddock/haddock"
cabal test
```
-#### Using Stack
-
-```bash
-stack init
-stack build
-# run the test suite
-export HADDOCK_PATH="$(stack exec which 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