How do I get documentation for my Haskell package onto Hackage?

Question

UPDATE: This question is now out of date. Hackage now uses Haskell version 7.10.2 to build, so the following failure does not occur. The change also appears to have broken some of the scripts mentioned in the answers.

How do I get documentation for my Haskell package onto Hackage?

My understanding what that Hackage would build them, but I get an error

Resolving dependencies...
cabal: Could not resolve dependencies:
trying: MyPackage-0.1.0.2 (user goal)
next goal: base (dependency of MyPackage-0.1.0.2)
rejecting: base-4.7.0.1/installed-e4b... (conflict: MyPackage => base>=4.8 &&
<4.9)
rejecting: base-4.8.1.0, 4.8.0.0, 4.7.0.2, 4.7.0.1, 4.7.0.0, 4.6.0.1, 4.6.0.0,
4.5.1.0, 4.5.0.0, 4.4.1.0, 4.4.0.0, 4.3.1.0, 4.3.0.0, 4.2.0.2, 4.2.0.1,
4.2.0.0, 4.1.0.0, 4.0.0.0, 3.0.3.2, 3.0.3.1 (global constraint requires
installed instance)
Dependency tree exhaustively searched.

I'm not able to downgrade the requirements for my package (which appears to be the obstacle to an automatic build) and I see that some packages say "Docs uploaded by user". However any attempt to build fails (see below.)

How do I get documentation for my Haskell package onto Hackage? In particular, what do I need to do to upload them myself?

---

I've tried

$ cp -R ./dist/doc/html/MyPackage/ MyPackage-0.1.0.2-docs
$ tar cvzf --format=ustar -f MyPackage-0.1.0.2-docs.tar.gz MyPackage-0.1.0.2-docs
$ curl -X PUT -H 'Content-Type: application/x-tar' -H 'Content-Encoding: gzip' --data-binary '@MyPackage-0.1.0.2-docs.tar.gz' 'https://hackage.haskell.org/package/MyPackage-0.1.0.2/docs' -u 'Rax'

but get

Invalid documentation tarball: File in tar archive is not in the expected directory 'MyPackage-0.1.0.2-docs'

---

name:                   MyPackage
version:                0.1.0.2
license:                BSD3
license-file:           LICENSE
-- copyright:           
category:               Development
build-type:             Simple
-- extra-source-files:  
cabal-version:          >= 1.22.1.1

library
    -- default-extensions: Trustworthy
    exposed-modules:    MyMod.A,
                        MyMod.A.B
    other-modules:      MyMod.C
    -- other-extensions:
    build-depends:      base >= 4.8.1.0 && <4.9,
                        containers >= 0.5.5.1,
                        split >= 0.2.2,
                        MissingH >= 1.3.0.1
    -- hs-source-dirs:
    default-language:   Haskell2010

---

I've also tried my own version of the several scripts linked below, but get the same error:

#!/bin/bash

cabal haddock --hyperlink-source --html-location='/package/$pkg-$version/docs'  --contents-location='/package/$pkg'
S=$?
if [ "${S}" -eq "0" ]; then
    cd "dist/doc/html"
    DDIR="${1}-${2}-docs"
    cp -r "${1}" "${DDIR}" && tar -c -v -z --format=ustar -f "${DDIR}.tar.gz" "${DDIR}"
    CS=$?
    if [ "${CS}" -eq "0" ]; then
        echo "Uploading to Hackage…"
        curl -X PUT -H 'Content-Type: application/x-tar' -H 'Content-Encoding: gzip' --data-binary "@${DDIR}.tar.gz" --digest --netrc "https://hackage.haskell.org/package/${1}-${2}/docs"
        exit $?
    else
        echo "Error when packaging the documentation"
        exit $CS
    fi
else
    echo "Error when trying to build the package."
    exit $S
fi

which I invoke with

myscript MyPackage 0.1.0.2

but get the same error.

Answer 1

Does your library require base >= 4.8.1.0?

That's the problem - Hackage is trying to use base == 4.7.0.1 which conflicts with your cabal file.

I would see if you can build your library with the base that Hackage is using.

Some links to uploading docs to Hackage yourself:

• http://fuuzetsu.co.uk/blog/posts/2014-01-06-Fix-your-Hackage-documentation.html

• https://gist.github.com/stbuehler/7068764

Answer 2

Even if the docs would build on hackage, they take some time to appear and at some point they were broken for an extended period of time. I got used to do it with the neil tool as described here:

http://neilmitchell.blogspot.si/2014/10/fixing-haddock-docs-on-hackage.html

I first install neil (in another sandbox on my disk), then, in the folder of your library:

neil docs --username=YourHackageUsername

It takes care of all the details for you!