diff options
| author | Simon Jakobi <simon.jakobi@gmail.com> | 2018-06-30 13:41:38 +0200 |
|---|---|---|
| committer | Simon Jakobi <simon.jakobi@gmail.com> | 2018-07-20 13:39:29 +0200 |
| commit | a532f8f0b81461849278b4cc5bc5b72521e516d1 (patch) | |
| tree | 654884c49227883216dbf2ee4a6cd19b33edac5f | |
| parent | 953e3eb86b57f468c68d6ec0c651e8b3feda1518 (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
(cherry picked from commit 61d6f935da97eb96685f07bf385102c2dbc2a33c)
| -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 +``` |