使用Haddock和stack为我自己的代码生成文档

Question

我已经用Haddock样式注释了我的代码，并希望生成可浏览的文档。由于我也在使用堆栈，因此我希望将文档生成集成到工作流中。但是，我还不能生成任何有用的东西。

我能跑

stack haddock

它将以我想要的方式生成文档(可以在~/.stack/内部找到)，但它似乎只为我所依赖的包生成文档，而不是为我自己的代码生成文档。

当我跑的时候

stack haddock --help

我得到的印象是，我可以使用额外的参数--haddock为我自己的项目生成文档，而使用--no-haddock-deps为我的依赖项省略文档。但是，当我运行

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

似乎什么都没发生。如果我先使用stack clean，它将重新编译我的所有代码，但不会生成任何与文档相关的输出。

作为中间解决方案，我也尝试过单独运行Haddock，即

haddock my-source.hs

但随后我得到一个错误，它找不到文件所依赖的模块(通过堆栈在本地安装)。这给我的印象是，文档生成必须以某种方式通过堆栈。我已经找到了关于配置.cabal和stack.yaml文件以获取文档的任何解释，但没有真正找到。

TL;DR

如何使用stack和Haddock为我自己的包中的代码生成文档？

Answer 1

根据堆栈问题跟踪器上的this ticket的说法，堆栈目前只能构建库的文档，而不能构建可执行文件。

可以使用以下命令将Cabal配置为使用堆栈数据库：

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

之后，您可以运行cabal haddock --executables来生成文档。

顺便说一下，stack haddock只是stack build --haddock的快捷方式，所以不需要编写stack haddock --haddock。

Answer 2

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

以下解决方案仅在指定单个文件时有效：

stack exec -- haddock --html src/Example.hs src/Main.hs --hyperlinked-source --odir=dist/docs