Broken documentation on Hackage.

[Peter Selinger]

I agree. Two of my packages are in your list: easyrender and newsynth
(both have "Nothing" for a reason in your list).

The problem for me is that, although you seem to have access to build
logs, I don't. I have not found the way to access the hackage build
logs for my packages or their documentation. Could you let me know
where I can find them?

For both packages, the documentation builds just fine on my local
machine. It also builds fine in a virtual machine, under Windows and
Ubuntu. Since I don't have access to Hackage's build logs, I cannot
really figure out why the documentation is not building there. This is
what has prevented me from fixing it. 

I even created "candidates" for the packages, before uploading the
packages to the main index. Again, the documentation did not build,
and again, I could not find any logs to tell me what went wrong. So
the whole "candidate" mechanism has so far been useless to me.

You mentioned that there is a way to upload the documentation
manually. I'd love to do that. But how? I don't see any buttons or
links on the package maintainer's pages that would allow me to do
that.

Any help appreciated, -- Peter

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:
> 
> * Dependencies fail to build so your package does
> * Your package fails to build directly
> * Your package requires non-cabal libraries which aren't installed
> * Your package requires different version of install libraries
> 
> While all of these are understandable, there also seem to be problems
> with some packages which are seemingly perfectly fine otherwise. This
> problem is not new and has been reported[1]. There is even a system in
> place with Hackage 2 that would grant package owners to manually upload
> documentation and a system where some people (trustees and package
> maintainers) have the ability to do things like deleting the broken docs
> to have the builder try again[3] but it seems that this isn't actually
> used[4].
> 
> Over night I hacked up a quick program to parse some Hackage parts to
> see just how much stuff was broken. I have only considered the most
> recent package versions. Out of the 7761 packages, 811 came up with
> missing documentations. While it is a big number (~9.56%), it includes
> every package on Hackage. Next thing that follows is to restrict the
> search a bit. Only considering packages from 2013 and the still very
> young 2014, 210 are missing documentation. 140 of those were uploaded
> since August 2013 (around the Hackage 2 move). Remember that this is
> only for most recent versions on Hackage. Assuming that we didn't have a
> large spike in package uploads in second half of 2013 (I don't know, are
> there any charts or something?), that's unreasonably more than in the
> first half of 2013.
> 
> It should be fairly clear that something is broken and I'd love to know
> what. I snooped around in #hackage today for a bit and there doesn't
> seem to be much sense of the urgency. Granted, people are busy but isn't
> this a pretty important issue? It's not like it's recent either.
> 
> What can we do? Why isn't it fixed? Are there any suspects? Why isn't
> the trustee system being used to mitigate this problem a bit while it's
> being fixed? Is there any way to improve the amount of things that can
> be built by trying to work out any of the points at the top of this
> e-mail? Honestly, scrolling through the build logs of packages, all
> failures seem reasonable (Haddock parse failure, no dependencies
> installed=85) and yet somehow I find myself having to click on older
> version of packages to get docs very often recently. What changed? Is
> there even anything to fix? Maybe I'm just getting unlucky with the
> packages I click on recently.
> 
> I have uploaded the list of packages with missing documentation that
> have been uploaded on Hackage in 2013 and 2014 to [5]. The format is:
> (packageUrl, MissingDocs (Maybe reason) packageVersion dateUploaded). If
> your package is on there, you might want to consider uploading the docs
> by hand for now! Packages with =91Nothing=92 for a reason have no build log.
> See [6] for a reason for those. See [7] for how to view build logs yourself.
> 
> PS: I'm unsure if these are the right lists to e-mail. I've been told
> that Cabal folk maintain Hackage issues and considering so many broken
> docs, libraries might also be interested in it. Feel free to point me
> elsewhere.
> PPS: There also seems to be a lot of 404 errors while trying to click on
> some docs on some older packages that probably existed in the past.
> Perhaps they were lost in the Hackage move or are a different issue all
> together.
> 
> [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
> -- =
> 
> Mateusz K.
> _______________________________________________
> cabal-devel mailing list
> cabal-devel at haskell.org
> http://www.haskell.org/mailman/listinfo/cabal-devel
>