35

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?

ErikR
  • 51,541
  • 9
  • 73
  • 124
Sam van Herwaarden
  • 2,321
  • 14
  • 27
  • 2
    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: https://github.com/commercialhaskell/stack/issues/729 (including suggested workaround for building docs for executables with "cabal haddock"). – Rüdiger Hanke Sep 22 '15 at 13:43
  • @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 Sep 22 '15 at 13:54

2 Answers2

19

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.

Sam van Herwaarden
  • 2,321
  • 14
  • 27
Rüdiger Hanke
  • 6,215
  • 2
  • 38
  • 45
  • I don't really understand the SO edit system yet :/ Maybe I'm going mad but I was fairly sure when I suggested the edit the `cabal configure` command was not yet in your post. Now the edit history says it was, making the edit meaningless. Anyway thanks for the answer and feel free to roll the edit back... – Sam van Herwaarden Sep 22 '15 at 14:51
  • 2
    @SamvanHerwaarden I believe for a few minutes after an answer is first posted, the author can edit it without it showing up in the history. Maybe that's what happened here. – Ørjan Johansen Sep 22 '15 at 23:31
  • 1
    Runing the `cabal configure ...` command returns a failure of `cabal: ghc-pkg dump failed` for me. – Chris Stryczynski Dec 16 '17 at 11:24
  • I'm facing the same issue as @ChrisStryczynski Is there a solution for `cabal: ghc-pkg dump failed`? – Saurabh Nanda Jul 26 '18 at 13:33
8

https://www.reddit.com/r/haskell/comments/5ugm9s/how_to_generate_haddock_docs_for_nonlibrary_code/ddtwqzc/

The following solution only works when individual files are specified:

stack exec -- haddock --html src/Example.hs src/Main.hs --hyperlinked-source --odir=dist/docs
Chris Stryczynski
  • 30,145
  • 48
  • 175
  • 286
  • Awesome, thanks! I get warnings about primitive types such as `Int` not being available. Any way to include docs for some specific types? – Erik Oct 11 '17 at 18:45