haskell - 如何为所有包自定义 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