如何为所有包自定义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构建的包、使用cabal install从Hackage安装的包，甚至是使用cabal sdist上载到Hackage的包

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