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

时间:2015-09-22 09:01:24

标签: haskell cabal haddock haskell-stack

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

我可以跑

stack haddock

它将生成我想要的样式的文档(在~/.stack/内深处找到),但它似乎只生成我依赖的包的文档,而不是我自己的代码。

当我跑步时

stack haddock --help

我得到的印象是我可以使用附加参数--haddock为我自己的项目生成文档,并--no-haddock-deps省略我的依赖项的文档。但是,当我跑

stack haddock --haddock --no-haddock-deps
似乎没有任何事情发生。如果我stack clean首先它将重新编译我的所有代码但是没有生成任何输出似乎与文档有关。

作为一种中间解决方案,我也试过自己运行Haddock,即

haddock my-source.hs

然后我收到一个错误,它找不到文件所依赖的模块(由堆栈本地安装)。这让我觉得文档生成必须以某种方式通过堆栈。我已经查找过,但没有真正找到与配置我的.cabalstack.yaml文件以进行文档相关的任何解释。

TL; DR

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

2 个答案:

答案 0 :(得分:15)

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

可以使用此命令将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

答案 1 :(得分:3)

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