Hackage documentation v2

Posted on January 6, 2014 by Fūzetsu

This is just a quick follow up to my yesterday’s post (Actually looking at the date, it was this morning. My sleep ‘schedule’ is all over.).

Here are a few issues with yesterday’s post:

  1. My instructions stated cd dist/doc instead of cd dist/doc/html
  2. Documentation generated with my instructions would not have package cross-linking (very important). The links would have your local file-system paths instead.
  3. Documentation generated with my instructions would not have the /proper/ Contents page when clicked on a link from documentation. It would still have the Contents page, just not the one generated by Hackage.

Here are the fixes to each problem:

  1. Replace the bad cd path. I have reflected this in the small Bash script I published yesterday as a Gist and as a file. I did hear that some people were struggling with it a bit (such as on OS X) so if it doesn’t work out of the box, please make educated edits as you see fit.

  2. You can generate links to the packages with docs already on Hackage by passing an extra flag to cabal haddock. It is

    --html-location='http://hackage.haskell.org/package/$pkg/docs'

    Make sure you include $pkg verbatim, Cabal handles it automatically.

  3. As above, we just need to add an extra cabal haddock flag:

    --contents-location='http://hackage.haskell.org/package/$pkg'

If there are any further mistakes, please let me know and I’ll post up corrections.

If you have a better script for doing the uploads, also let me know and I’ll be happy to post it up if you want me to. Easy improvements would be to get the package version and package name from the cabal file.

Fan service.