Broken documentation on Hackage.

[Carter Schonwald]

agreed, cabal-install should definitely get support for doing this
correctly added in.  (since this is going to become a common activity for
maintainers who's libs need extra things installed that the doc builders
lack)

Any volunteers?


On Mon, Jan 6, 2014 at 9:28 PM, Mateusz Kowalczyk
<fuuzetsu at fuuzetsu.co.uk>wrote:

> On 07/01/14 01:23, Peter Selinger wrote:
> > 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".
>
> Ah, I do not use frames so I did not notice.
>
> > 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.:
> >
> > <meta HTTP-EQUIV="REFRESH" content="0; url=
> http://hackage.haskell.org/package/newsynth-0.1.0.0">
> > If your browser does not take you there automatically, please go to
> > <a href=http://hackage.haskell.org/package/newsynth-0.1.0.0>
> http://hackage.haskell.org/package/newsynth-0.1.0.0</a>.
> >
> > 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.
>
> That looks very useful but I have a few questions about it:
> * Why a Makefile as opposed to a Bash script or something? I don't
> think there's a way to pass arguments into a Makefile like to Bash
> scripts, save for environmental variables. I'd much rather prefer a
> command line flag for a script in my PATH rather than having to change
> the file each time.
>
> * This file makes us change the top two lines (user and package name)
> and uses ‘read’ for everything else. Why not fully go with one way or
> the other? Personally, I'd prefer arguments rather than ‘read’ (much
> easier to repeat commands/script against) but it's up to personal taste.
>
> * Can we not grab to project name from the cabal file just like you do
> with version?
>
> * Your ‘--html-location’ has ‘$$pkg’ in it, how come? Is that some
> kind of escape?
>
> * Considering you seem to know what you're doing much more than I am,
> is there any way to detect cabal sandboxes?
>
> I'm trying your makefile now (running with make -f /tmp/Makefile
> doc-upload) and
> it's giving me an error:
>
> ```
> [snip]
> Haddock coverage:
>  100% ( 18 / 18) in 'Yi.Style.Monokai'
> Documentation created: dist/doc/html/yi-monokai/index.html
> rm -r yi-monokai-0.1.1.1-docs
> rm: cannot remove ‘yi-monokai-0.1.1.1-docs’: No such file or directory
> make: *** [yi-monokai-0.1.1.1-docs.tar.gz] Error 1
> ```
>
> It works fine if I comment out the ‘rm -r’. Perhaps that should be
> allowed to fail somehow.
>
> > 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
>
> I think that cabal-install should really have the option to do all
> this rather than have people write up scripts like this, resulting in
> trial and error.
>
> --
> Mateusz K.
> _______________________________________________
> cabal-devel mailing list
> cabal-devel at haskell.org
> http://www.haskell.org/mailman/listinfo/cabal-devel
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.haskell.org/pipermail/libraries/attachments/20140106/18079101/attachment.html>