diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 58 |
1 files changed, 16 insertions, 42 deletions
@@ -1,52 +1,21 @@ # Haddock, a Haskell Documentation Tool [](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. |