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?

Answer 1

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.