Commit 8c653263 authored by Alec Theriault's avatar Alec Theriault

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
parent 7013f52c
# 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
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment