manual documentation uploads are not documented

[RossPaterson]

I understand that maintainers can upload docs if the builder can't build them, via

http://beta.hackage.haskell.org/api#documentation-core

but several points aren't documented:

• The flags that should be given to cabal to get the links right.
• The directory that needs to be tarred.
• How the tar file should be uploaded.

[dcoutts]

Some info, since I was working on a related bit of the code. Just need to collect it and turn it into a user-oriented page.

The flags that should be given to cabal to get the links right.

One can find this from the build client code. It invokes cabal-install with the appropriate args.

Though perhaps better to explain it as a cabal haddock invocation.

The directory that needs to be tarred.

Tarball content needs to be like:

zlib-0.5.3.1-docs/
zlib-0.5.3.1-docs/src/
zlib-0.5.3.1-docs/src/Codec-Compression-Zlib.html

... etc

How the tar file should be uploaded.

Like so:

curl -X PUT \
 -H "Content-Type: application/x-tar" \
 -H "Content-Encoding: gzip" \
 http://user:passwd@beta.hackage.haskell.org/package/zlib-0.5.3.1/docs \
 --data-binary @zlib-0.5.3.1-docs.tar.gz

[jeremyjh]

Hi, when I try to do this using your command @dcoutts I get an error message:

 Invalid documentation tarball: Archive is in the GNU tar format

I'm creating the tarball with:

tar -czf my_dir

[gracenotes]

Most tar programs read/write in the portable ustar format. "--format=ustar" should do the trick here.

[jeremyjh]

Thanks @gracenotes - that seems to work - at least I do not get any error message. I don't see my docs showing up either though.

[gracenotes]

Okay, I took a look at /package/higher-leveldb-0.1.0.0/docs.tar. In the tarball, the higher-leveldb-0.1.0.0-docs/src/ directory is meant for Haddock coloured source files; the top-level directory (right under higher-leveldb-0.1.0.0-docs/) is meant for the documentation itself. You'll also need ocean.css etc. in this top-level directory; some of the generation flags can be seen here: https://github.com/haskell/hackage-server/blob/2657af5/BuildClient.hs#L513

hackage-build itself should probably be easier to use for one-off documentation uploads.

[jeremyjh]

Great, that did it thanks!

[cartazio]

bump :)

[stbuehler]

I wrote a shell script to generate and upload docs for a package: https://gist.github.com/stbuehler/7068764

[cartazio]

this information needs to be more discoverable and easy to use until the broken docs problem is resolved

[Gabriella439]

I can confirm that stbuehler's script works. I was a bit suspicious at first because I didn't see any index.html file in the generated documentation, but I went ahead and tried it and it worked.

[dcoutts]

Note that we're now running a new doc builder client which should resolve some of these issues. For the things not resolved, it does at least generate build logs (see /package/foo-1.0/reports/$n/log) so we can see what's wrong. Mostly I expect this will now be missing C libs which we'll need to add to the builder machine.

[mruegenberg]

I just tried the process mentioned here. I managed to upload documentation, but it is actually not unpacked correctly.

The package is hydra-hs, the doc link (correctly) goes here, but the actual documentation is in a subdirectory here.
I then tried to create and upload the archive from the subdirectory that, when unpacked in the same way, would result in the correct paths, but that gave me an "Invalid documentation tarball" message.