From 214aaf35d0d1c231dbae55dc6a1f9d5543218439 Mon Sep 17 00:00:00 2001 From: Alex Biehl Date: Thu, 23 Mar 2017 17:49:32 +0100 Subject: Include travis build indication badge --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 160ee995..23d0dd0b 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Haddock, a Haskell Documentation Tool +# Haddock, a Haskell Documentation Tool [![Build Status](https://travis-ci.org/haskell/haddock.svg?branch=master)](https://travis-ci.org/haskell/haddock) #### About haddock -- cgit v1.2.3 From 53598f89117d3a860eaf11ec44f93acf708b93c1 Mon Sep 17 00:00:00 2001 From: Herbert Valerio Riedel Date: Thu, 20 Jul 2017 12:18:38 +0200 Subject: Mention new-build in README --- README.md | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index 23d0dd0b..a21b29e9 100644 --- a/README.md +++ b/README.md @@ -59,6 +59,14 @@ Clone the repository: 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-8.2.1 +# build & run the test suite +cabal new-test -w ghc-8.2.1 +``` + ###### Using Cabal sandboxes ```bash -- cgit v1.2.3 From cc1577ae29763dfeb9483b5c7dcc723bb3a014f0 Mon Sep 17 00:00:00 2001 From: Herbert Valerio Riedel Date: Thu, 20 Jul 2017 12:32:16 +0200 Subject: Update README Also improves markup and removes/fixes redundant/obsolete parts [skip ci] --- README.md | 58 ++++++++++++++++------------------------------------------ 1 file changed, 16 insertions(+), 42 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index a21b29e9..3e356ecc 100644 --- a/README.md +++ b/README.md @@ -1,52 +1,21 @@ # Haddock, a Haskell Documentation Tool [![Build Status](https://travis-ci.org/haskell/haddock.svg?branch=master)](https://travis-ci.org/haskell/haddock) -#### About haddock +## About haddock -This is Haddock, a tool for automatically generating documentation -from annotated Haskell source code. It is primary intended for -documenting library interfaces, but it should be useful for any kind -of Haskell code. +See [Description on Hackage](https://hackage.haskell.org/package/haddock). -Haddock lets you write documentation annotations next to the -definitions of functions and types in the source code, in a syntax -that is easy on the eye when writing the source code (no heavyweight -mark-up). The documentation generated by Haddock is fully hyperlinked -- click on a type name in a type signature to go straight to the -definition, and documentation, for that type. +## Source code documentation -Haddock understands Haskell's module system, so you can structure your -code however you like without worrying that internal structure will be -exposed in the generated documentation. For example, it is common to -implement a library in several modules, but define the external API by -having a single module which re-exports parts of these implementation -modules. Using Haddock, you can still write documentation annotations -next to the actual definitions of the functions and types in the -library, but the documentation annotations from the implementation -will be propagated to the external API when the documentation is -generated. Abstract types and classes are handled correctly. In -fact, even without any documentation annotations, Haddock can generate -useful documentation from your source code. - - -#### Documentation formats - -Haddock can generate documentation in multiple formats; currently HTML -is implemented, and there is partial support for generating LaTeX and -Hoogle. - - -#### Source code documentation - -Full documentation can be found in the doc/ subdirectory, in DocBook +Full documentation can be found in the `doc/` subdirectory, in +[reStructedText format](http://www.sphinx-doc.org/en/stable/rest.html) format. - -#### Contributing +## Contributing Please create issues when you have any problems and pull requests if you have some code. -##### Hacking +## Hacking To get started you'll need a latest GHC release installed. @@ -59,7 +28,7 @@ Clone the repository: and then proceed using your favourite build tool. -###### Using [`cabal new-build`](http://cabal.readthedocs.io/en/latest/nix-local-build-overview.html) +#### Using [`cabal new-build`](http://cabal.readthedocs.io/en/latest/nix-local-build-overview.html) ```bash cabal new-build -w ghc-8.2.1 @@ -67,7 +36,7 @@ cabal new-build -w ghc-8.2.1 cabal new-test -w ghc-8.2.1 ``` -###### Using Cabal sandboxes +#### Using Cabal sandboxes ```bash cabal sandbox init @@ -83,7 +52,7 @@ export HADDOCK_PATH="dist/build/haddock/haddock" cabal test ``` -###### Using Stack +#### Using Stack ```bash stack init @@ -93,9 +62,14 @@ 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 instead of master. +changes, you should be working on `ghc-head` branch instead of `master`. 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. -- cgit v1.2.3