diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 109 |
1 files changed, 52 insertions, 57 deletions
@@ -1,68 +1,63 @@ -# Haddock, a Haskell Documentation Tool [](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) +Note: before building `haddock`, you need to build the subprojects +`haddock-library` and `haddock-api`, in this order! +The `cabal v2-build` takes care of this automatically. + +#### Using [`cabal v2-build`][cabal v2] ```bash -cabal new-build -w ghc-head -# build & run the test suite -cabal new-test -w ghc-head all +cabal v2-build -w ghc-8.10.1 +cabal v2-test -w ghc-8.10.1 all ``` -#### Using Cabal sandboxes +#### Using `stack` + +```bash +stack init +stack build +export HADDOCK_PATH="$(stack exec which haddock)" +stack test +``` + +#### Using Cabal sandboxes (deprecated) ```bash cabal sandbox init @@ -78,29 +73,29 @@ 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 +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 |