aboutsummaryrefslogtreecommitdiff
path: root/README.md
blob: 978dea3ef3b6959e6a7e05af213f7152d273d9f8 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
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
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
# 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.


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


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

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