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.

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.

Your tar command ends with MyPackage-0.0.1.3-docs, which doesn't match the version in the rest. Did you perhaps pack the wrong one by accidental tab completion? — Ørjan Johansen
What version of haddock are you using? I remember it used to get the links all wrong. I have been using github.com/michaelt/streaming/blob/master/upload.sh with Haddock version 2.16.1 (Add your user name when you call "sh upload.sh MyHackageName") Also, I think "cabal-version: >= 1.10" should be fine. — Michael

ErikR ErikR · Accepted Answer · 2015-09-24T19:35:06

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:

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

2 Answers