10

It's not clear to me how to customize the documents that

cabal haddock

generates. For example how do I include source links, or use a custom CSS file so that they apply in all cases?

In my ~/.cabal/config I've tried

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:

but it's unclear to me what the scope if these settings is.

How do I customize the default document generation for all documents generated by Haddock: packages I build with cabal haddock, for packages I install from Hackage with cabal install, and even to packages I upload to Hackage with cabal sdist?

orome
  • 45,163
  • 57
  • 202
  • 418

1 Answers1

0

First of all, the settings in ~/.cabal/config are your per-user default settings. Your alterations would come into effect, whenever you call cabal haddock.

Since the haddock documentation is built statically for each package, you would need to rerun the cabal haddock command for every package you install to change the appearance of its docs.

Also you seem to have mixed up something a little: cabal sdist does not upload anything to Hackage. That's what cabal upload is for.

Usually you just upload the bare package to Hackage and the server builds the documentation himself, but there is a way to upload the documentation you built yourself, in case the server fails to build it or for other reasons. I use the following script I found at http://hackage.haskell.org/upload with some alterations:

#!/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
  • 88
  • 7