如何定制所有包的Haddock文档生成？

Question

我不清楚如何自定义这些文档。

cabal haddock

例如，我如何包含源链接或使用自定义CSS文件，以便它们适用于所有情况下？

在我的〜/ .cabal / config 中，我尝试了

haddock
  -- keep-temp-files: False
  -- hoogle: False
  -- html: False
  -- html-location:
  -- executables: False
  -- tests: False
  -- benchmarks: False
  -- all:
  -- internal: False
  css: /Users/Rax/Projects/Haskell/Package/mystuff.css
  hyperlink-source: True
  -- hscolour-css:
  -- contents-location:

但是我不清楚这些设置的范围是什么。

我该如何定制Haddock生成的所有文档的默认文档，无论是使用cabal haddock构建的软件包，还是从Hackage安装的软件包使用cabal install，甚至对我使用cabal sdist上传到Hackage的软件包都起作用？

- orome

Answer 1

首先，~/.cabal/config 中的设置是您每个用户的默认设置。只要您调用 cabal haddock，您的更改就会生效。

由于 haddock 文档为每个软件包静态构建，因此您需要重新运行 cabal haddock 命令来更改其文档的外观，对于每个安装的软件包都需要如此。

另外，您似乎有点混淆了：cabal sdist 不会上传任何内容到 Hackage。这就是 cabal upload 的作用。

通常，您只需将裸软件包上传到 Hackage，服务器会自己构建文档，但如果服务器无法构建文档或出现其他问题，您可以上传自己构建的文档。我使用了在 http://hackage.haskell.org/upload 找到的以下脚本，并进行了一些修改：

#!/bin/sh
set -e

dir=$(mktemp -d dist-docs.XXXXXX)
trap 'rm -rf "$dir"' EXIT

cabal haddock --builddir="$dir" --for-hackage --haddock-option=--hyperlinked-source
# Starting with cabal 2.0, `--publish` is needed for uploading to non-candidate releases
cabal upload -d $dir/*-docs.tar.gz --publish

- nek0