Broken documentation on Hackage.

Tue Jan 7 01:23:09 UTC 2014

Thanks, that's even better! 

However, I find that the --contents-location option to cabal haddock
does not work properly.  Apparently it not only prevents index.html
from being built (which makes modest sense), but it also prevents
index-frames.html from being built (which does not). So in the frames
view, one of the frames will just say "Sorry, it's just not here".
That's not very nice. Also, if one loads the "/frames.html" URL
directly, it still points to the non-existing index.html, rather than
the one given by --contents-location. I think these are bugs. 

For example, see
http://hackage.haskell.org/package/yi-monokai-0.1.1.1/docs/Yi-Style-Monokai.html
and click on "Frames".

One workaround is to run "cabal haddock" twice: first without the
--contents-location option, and then with it. Slightly annoying, but
it works. It has the disadvantage that if one goes directly to the
".../frames.html" URL, one will still see the old index.html. 

Another workaround is to omit the --contents-location option
altogether, and to manually create an index.html that is just a
forward to the correct location, i.e.:

Only this last solution seems to do the correct thing all the time. 
For an example, see
http://hackage.haskell.org/package/newsynth-0.1.0.0/docs/frames.html

Your instructions have been *very* helpful. But it's a lot of details
and finnicky cabal directives to keep track of for doing this all the
time. I've turned your instructions into a Makefile to automate this
task; see attached. In principle, only the first two lines should need
to be customized. Then "make doc-upload" will build the documentation
and upload it correctly.

I know, Cabal somehow was supposed to make Makefiles obsolete. Alas.
Fortunately, the Makefile is only for the package maintainer, and not
for the package user.

-- Peter

Mateusz Kowalczyk wrote:
> 
> On 05/01/14 10:15, Mateusz Kowalczyk wrote:
> > Hi all,
> > 
> > It seems that we are having a rather big issue with Hackage in recent
> > months and I'm sure many of you have noticed: a lot of packages aren't
> > getting their docs built. As far as I can tell, there can be multiple
> > reasonable causes:
> >
> > [snip]
> > 
> > [1]: https://github.com/haskell/hackage-server/issues/145
> > [2]:
> > https://github.com/haskell/hackage-server/issues/145#issuecomment-29468613
> > [3]:
> > https://github.com/haskell/hackage-server/issues/145#issuecomment-29422332
> > [4]: http://hackage.haskell.org/packages/trustees/
> > [5]: http://fuuzetsu.co.uk/misc/sorted.txt
> > [6]:
> > https://github.com/haskell/hackage-server/issues/145#issuecomment-30129142
> > [7]:
> > https://github.com/haskell/hackage-server/issues/145#issuecomment-29472445
> > 
> 
> Greetings again,
> 
> After some feedback from people over yesterday and some digging today,
> few things became apparent:
> * cross-package linking is broken with manual documentation
> * ‘Contents’ link takes you somewhere else now
> * I said ‘cd dist/doc’ instead of ‘cd dist/doc/html’
> 
> Here is what you can do to fix the package links and contents page:
> add the following flags to the ‘cabal haddock’ command:
> 
> --html-location='http://hackage.haskell.org/package/$pkg/docs'
> --contents-location='http://hackage.haskell.org/package/$pkg'
> 
> I'm not sure of implication of this for specific version package links.
> Note also that you do need to put in ‘$pkg’, that is a cabal directive.
> 
> As usual, I welcome any comments and improvements.
> -- 
> Mateusz K.
> _______________________________________________
> cabal-devel mailing list
> cabal-devel at haskell.org
> http://www.haskell.org/mailman/listinfo/cabal-devel
> 

-------------- next part --------------
A non-text attachment was scrubbed...
Name: Makefile
Type: application/octet-stream
Size: 1569 bytes
Desc: Makefile
URL: <http://www.haskell.org/pipermail/cabal-devel/attachments/20140106/d545d4f8/attachment.obj>