stack haddock --executables

[rimmington]

There doesn't seem to be an equivalent to cabal haddock --executables. One of our projects has significant executable-only code that it would be useful to generate Haddocks for.

As a workaround, you can configure Cabal to use Stack DBs and then cabal haddock --executables.

[borsboom]

Agreed, this would be nice to have. A PR would be welcome, but if not forthcoming I hope to be able to get to this at some point myself.

[nd2s]

+1

[trskop]

:+1:

[Siprj]

:+1:

[jasonzoladz]

Pretty please :)

[ChristopherKing42]

http://stackoverflow.com/questions/32712775/generating-documentation-for-my-own-code-with-haddock-and-stack

[mgsloan]

Given the popularity of this issue, I took a look at implementing it.

I tried to use cabal, in order to see what it does to have haddock generate docs. I immediately ran into https://github.com/haskell/cabal/issues/1919 even on the most trivial stack new project, with Cabal-1.22.7.0

Unfortunately, this seems to be an issue with Cabal the library, which we currently use for running haddock, so it also affects stack. I'm not sure I want to expose such brokenness to people.

If I copy out the command used to run haddock, I get /home/mgsloan/.stack/setup-exe-cache/x86_64-linux/setup-Simple-Cabal-1.22.7.0-ghc-7.10.3 --builddir=.stack-work/dist/x86_64-linux/Cabal-1.22.7.0 haddock --html --hoogle --html-location=../$pkg-$version/ --hyperlink-source. If I toss --all on there, to haddock all components, I get setup-Simple-Cabal-1.22.7.0-ghc-7.10.3: internal error when calculating transitive package dependencies. :(

Perhaps we should consider doing our own implementation of running haddock. PRs welcome, all ye that want docs in components other than libraries!

[cblp]

:+1:

[borsboom]

There are other good reasons to, as @mgsloan suggested, not use Cabal's implementation of building haddocks (e.g., then we wouldn't have to rebuild a package to build its haddocks), so I think that's definitely the way forward.

[fosskers]

I just hit this issue, expecting stack haddock to "just work" for executables. It's definitely handy for browsing the API of a executable monolith's backend.

[runeksvendsen]

It's worth noting that, if you develop your executables as tiny wrappers around a library -- with all the important stuff in the library -- then you have all the documentation in that library, and therefore no need to depend on Haddock to work for executables. The executable itself would literally just be module Main where; import qualified SuperServer.App as App; main = App.main), so there's nothing to document there, really.

[kidonm]

👍

[dbaynard]

Running haddock for tests would be good, too.