From 9bd2bf9e8cbf1b2cc2affd27096b79d149528c5b Mon Sep 17 00:00:00 2001 From: Njagi Mwaniki Date: Sat, 27 Dec 2014 23:28:59 +0300 Subject: Turn the README into GitHub Markdown format. Closes #354 --- README.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100644 index 00000000..b85d99b7 --- /dev/null +++ b/README.md @@ -0,0 +1,47 @@ +# Haddock, a Haskell Documentation Tool + + +#### 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. + +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. + +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 +format. + + +#### Contributing + +Please create issues when you have any problems and pull requests if you have some code. -- cgit v1.2.3 From fb5d8584779da51521e8bf745e8627b5ddf3724d Mon Sep 17 00:00:00 2001 From: Bartosz Nitka Date: Sun, 7 Jun 2015 08:40:59 -0700 Subject: Add some Hacking docs for getting started --- README.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index b85d99b7..fba02bde 100644 --- a/README.md +++ b/README.md @@ -45,3 +45,22 @@ format. #### Contributing Please create issues when you have any problems and pull requests if you have some code. + +###### Hacking + +To get started you'll need a latest GHC release installed. + + git clone https://github.com/haskell/haddock.git + cd haddock + cabal sandbox init + cabal sandbox add-source haddock-library + cabal sandbox add-source haddock-api + # adjust -j to the number of cores you want to use + cabal install -j4 --dependencies-only --enable-tests + cabal configure --enable-tests + cabal build -j4 + # run the test suite + cabal test + +If you want to build against `GHC HEAD`, `ghc-head` is the corresponding branch. +Note that it doesn't have to be up to date. -- cgit v1.2.3 From 2d1b63e9f01b0a926ef4f8ca8de800bc8a4f27cc Mon Sep 17 00:00:00 2001 From: Bartosz Nitka Date: Sun, 7 Jun 2015 08:44:30 -0700 Subject: Fix markdown --- README.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index fba02bde..f6dd00d4 100644 --- a/README.md +++ b/README.md @@ -50,6 +50,7 @@ Please create issues when you have any problems and pull requests if you have so To get started you'll need a latest GHC release installed. +```bash git clone https://github.com/haskell/haddock.git cd haddock cabal sandbox init @@ -61,6 +62,7 @@ To get started you'll need a latest GHC release installed. cabal build -j4 # run the test suite cabal test +``` If you want to build against `GHC HEAD`, `ghc-head` is the corresponding branch. Note that it doesn't have to be up to date. -- cgit v1.2.3 From a65953de929fd9488250f8e0257c918465193e43 Mon Sep 17 00:00:00 2001 From: Mateusz Kowalczyk Date: Mon, 8 Jun 2015 15:08:36 +0100 Subject: Refine hacking instructions slightly --- README.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index f6dd00d4..31015e91 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,8 @@ Please create issues when you have any problems and pull requests if you have so ###### Hacking -To get started you'll need a latest GHC release installed. +To get started you'll need a latest GHC release installed. Below is an +example setup using cabal sandboxes. ```bash git clone https://github.com/haskell/haddock.git @@ -64,5 +65,8 @@ To get started you'll need a latest GHC release installed. cabal test ``` -If you want to build against `GHC HEAD`, `ghc-head` is the corresponding branch. -Note that it doesn't have to be up to date. +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. +See instructions at +https://ghc.haskell.org/trac/ghc/wiki/WorkingConventions/Git/Submodules +for an example workflow. -- cgit v1.2.3