Generating documentation for my own code with Haddock and stack

Question

I have annotated my code in Haddock style and would like to generate browse-able documentation. Since I am also using stack, I want to integrate the documentation generation into the workflow. However, I have not yet been able to generate anything useful.

I can run

stack haddock

and it will generate documentation in the style I want (to be found deep inside ~/.stack/), but it only seems to generate documentation for the packages I depend on, rather than for my own code.

When I run

stack haddock --help

I get the impression that I can use the additional argument --haddock to generate documentation for my own project, and --no-haddock-deps to leave out the documentation for my dependencies. However, when I run

stack haddock --haddock --no-haddock-deps

nothing seems to happen. If I stack clean first it will recompile all my code but no output is generated seeming to relate in any way to documentation.

As an intermediate solution I have also tried running Haddock by itself, i.e.

haddock my-source.hs

but then I get an error that it cannot find a module the file depends on (which is installed locally by stack). This gives me the impression that documentation generation will have to go through stack somehow. I have looked for, but not really found any explanations related to configuring my .cabal and stack.yaml files for documentation.

TL;DR

How can I use stack and Haddock to generate documentation for the code in my own package?

Is your project an executable or a library? I think stack only generates docs for libraries currently (for those it prints the path to the docs after the command, or you can see it from stack path), see here: github.com/commercialhaskell/stack/issues/729 (including suggested workaround for building docs for executables with "cabal haddock"). — Rüdiger Hanke
@RüdigerHanke: Great, thanks. With that link I worked it out, indeed using cabal haddock and the linked suggested workaround. If you want to write it out as an answer I'll accept it, if not I can write up the solution myself. (My project is an executable.) — Sam van Herwaarden

Rüdiger Hanke Rüdiger Hanke · Accepted Answer · 2015-09-22T14:00:16

According to this ticket on the stack issue tracker, Stack can currently only build documentation for libraries, but not executables.

Cabal can be configured to work with the stack databases with this command:

cabal configure --package-db=clear --package-db=global --package-db=$(stack path --snapshot-pkg-db) --package-db=$(stack path --local-pkg-db)

after which you can run cabal haddock --executables to generate the documentation.

By the way, stack haddock is only a shortcut for stack build --haddock, so there is no need to write stack haddock --haddock.

Generating documentation for my own code with Haddock and stack

2 Answers