aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSimon Jakobi <simon.jakobi@gmail.com>2018-06-30 13:41:38 +0200
committerSimon Jakobi <simon.jakobi@gmail.com>2018-07-20 13:39:29 +0200
commita532f8f0b81461849278b4cc5bc5b72521e516d1 (patch)
tree654884c49227883216dbf2ee4a6cd19b33edac5f
parent953e3eb86b57f468c68d6ec0c651e8b3feda1518 (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.md41
1 files changed, 36 insertions, 5 deletions
diff --git a/README.md b/README.md
index bfc2261b..51642aab 100644
--- a/README.md
+++ b/README.md
@@ -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
+```