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 <fuuze...@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@haskell.org > http://www.haskell.org/mailman/listinfo/cabal-devel >
_______________________________________________ cabal-devel mailing list cabal-devel@haskell.org http://www.haskell.org/mailman/listinfo/cabal-devel
