diff options
| author | Simon Jakobi <simon.jakobi@gmail.com> | 2018-06-30 13:41:38 +0200 |
|---|---|---|
| committer | Alexander Biehl <alexbiehl@gmail.com> | 2018-06-30 13:41:38 +0200 |
| commit | 61d6f935da97eb96685f07bf385102c2dbc2a33c (patch) | |
| tree | d203d832993a9f06defec9917978cb45fe01bc83 | |
| parent | 9339517a2bd1c16c1d11e66d9c754f0ef702f99a (diff) | |
README updates (#856)
* README: Remove mentions of master branch
* README: Add instructions for using html-test
* README: Change command to run _all_ the testsuites
* README: Add project overview section
| -rw-r--r-- | README.md | 41 |
1 files changed, 36 insertions, 5 deletions
@@ -11,6 +11,32 @@ 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. @@ -33,7 +59,7 @@ and then proceed using your favourite build tool. ```bash cabal new-build -w ghc-8.4.1 # build & run the test suite -cabal new-test -w ghc-8.4.1 +cabal new-test -w ghc-8.4.1 all ``` #### Using Cabal sandboxes @@ -65,11 +91,16 @@ 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 instead of `master`. +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. -The `master` branch usually requires a GHC from the latest GHC stable -branch. The required GHC version can be inferred from the version -bounds on `ghc` in the respective `.cabal` files. +### 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 +``` |