README.md 2.63 KB
Newer Older
1
# Haddock, a Haskell Documentation Tool [![Build Status](https://travis-ci.org/haskell/haddock.svg?branch=ghc-8.6)](https://travis-ci.org/haskell/haddock)
2 3


Herbert Valerio Riedel's avatar
Herbert Valerio Riedel committed
4
## About haddock
5

Herbert Valerio Riedel's avatar
Herbert Valerio Riedel committed
6
See [Description on Hackage](https://hackage.haskell.org/package/haddock).
7

Herbert Valerio Riedel's avatar
Herbert Valerio Riedel committed
8
## Source code documentation
9

Herbert Valerio Riedel's avatar
Herbert Valerio Riedel committed
10 11
Full documentation can be found in the `doc/` subdirectory, in
[reStructedText format](http://www.sphinx-doc.org/en/stable/rest.html)
12 13
format.

14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39

## 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-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.


Herbert Valerio Riedel's avatar
Herbert Valerio Riedel committed
40
## Contributing
41 42

Please create issues when you have any problems and pull requests if you have some code.
43

Herbert Valerio Riedel's avatar
Herbert Valerio Riedel committed
44
## Hacking
45

46 47 48
To get started you'll need a latest GHC release installed.

Clone the repository:
49

Bartosz Nitka's avatar
Bartosz Nitka committed
50
```bash
51 52
  git clone https://github.com/haskell/haddock.git
  cd haddock
53 54 55 56
```

and then proceed using your favourite build tool.

Herbert Valerio Riedel's avatar
Herbert Valerio Riedel committed
57
#### Using [`cabal new-build`](http://cabal.readthedocs.io/en/latest/nix-local-build-overview.html)
58 59

```bash
60
cabal new-build -w ghc-8.6.1
61
# build & run the test suite
62
cabal new-test -w ghc-8.6.1 all
63 64
```

Herbert Valerio Riedel's avatar
Herbert Valerio Riedel committed
65
#### Using Cabal sandboxes
66 67

```bash
68 69 70 71 72 73 74 75 76 77 78
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
Bartosz Nitka's avatar
Bartosz Nitka committed
79
```
80

Herbert Valerio Riedel's avatar
Herbert Valerio Riedel committed
81
#### Using Stack
82 83

```bash
84
stack init
85
stack build
86
# run the test suite
87
export HADDOCK_PATH="$(stack exec which haddock)"
88
stack test
89 90
```

Herbert Valerio Riedel's avatar
Herbert Valerio Riedel committed
91
### Git Branches
92

93
If you're a GHC developer and want to update Haddock to work with your
94
changes, you should be working on `ghc-head` branch.
95 96 97
See instructions at
https://ghc.haskell.org/trac/ghc/wiki/WorkingConventions/Git/Submodules
for an example workflow.
Herbert Valerio Riedel's avatar
Herbert Valerio Riedel committed
98

99 100 101 102 103 104 105 106
### Updating `html-test`

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
```