Regeneration of the Haddock documentation

[kseo]

If the generation of the Haddock documentation fails for some reasons, there is no way to re-trigger the build without uploading a new version of the package.

It would be nice if there is a way to re-trigger the build.

[gbaz]

No way to do it now :-/

I agree this would be a good feature.

[crockeea]

The only reason I've seen documentation fail to build is due to missing dependencies on the build system (for example, LLVM). In that case, retriggering a build won't help. What is a case where docs might fail to build, but might succeed upon a rebuild?

[kseo]

@crockeea For some unknown reasons, the Hackage server does not start building the documentation from time to time. Many people upload a new package by incrementing the version number just to re-trigger the build even though there are no missing dependencies.

[crockeea]

When Hackage doesn't start building the docs at all, then you're already hitting a known Hackage bug. In your question, you ask about what happens if the docs fail for some reason (i.e., a build report is generated, but the docs failed to build).

There actually is a button for "delete documentation and trigger rebuild" (click "edit package information", then the package version under "Manage documentation", then "delete documentation and trigger rebuild".) However, this is designed not to trigger a rebuild if there is a failed build report, likely for the reason I pointed out above: if it didn't succeed once, it won't succeed on round two.

In the case that no build report was generated, I don't know what the "rebuild" button is designed to do

[kseo]

I agree that the rebuild button is not of much use once the bug #478 is fixed.

[Blaisorblade]

I agree that the rebuild button is not of much use once the bug #478 is fixed.

Disagree—cabal builds are a function of the global state of Hackage and on all package bounds (which can be edited after the fact), so they aren't deterministic.

For example, http://hackage.haskell.org/package/happstack-server-7.4.6.2/reports/1 fails because threads wasn't compatible with base-4.9 (hence GHC 8.0), but that was fixed by http://hackage.haskell.org/package/threads-0.5.1.4.

Package candidates are another use case for rebuilds, since the package itself can change. See #512.

More in general, deterministic builds require bug-free software seldom available, and Travis rebuild button is very visible and often used.

Finally, fixing #478 appears tricky. Could fixing this bug (if there's anything to do) be easier?

However, this is designed not to trigger a rebuild if there is a failed build report, likely for the reason I pointed out above: if it didn't succeed once, it won't succeed on round two.

I propose to change that.

In the case that no build report was generated, I don't know what the "rebuild" button is designed to do

In this other scenario, it should probably trigger a new build, as hinted by
this comment by @dcoutts.

The current button invokes DELETE on a slightly different URL (only for docs), but I guess the functionality should be similar:
https://github.com/haskell/hackage-server/blob/4e7db73bd5149192211202538404802a07d7ede5/datafiles/templates/Html/maintain-docs.html.st

[gbaz]

The issue is the following: To prevent retrying failed builds forever, the hackage-builder keeps a list of "failed" packages, and gives up after 3 failures. This list of failed packages exists on the hackage-builder box, entirely distinct from Hackage. When the documentation is deleted, this doesn't clear the failures from the failed file. How could it?

So what we need is some better mechanism for requesting doc-builds than currently exists. In particular, the current mechanism is just "look for all packages without docs, subtract all packages that are sufficiently failed, then build the rest."

A proposed new mechanism would be: Download a list of all packages for which hackage-server requests docs, then build those. In turn, hackage-server would maintain its own state regarding failed builds, requested rebuilds, etc.

[hsyl20]

The haddock of a package of mine failed to build because dependencies on base were too strict (< 4.12) once Hackage switched to ghc-8.6 to build the docs. I've made a revision but still can't build the doc. I guess packages with new revisions should be considered as new packages for the doc builder.

[gbaz]

With the new docbuilder work this is fixed, one can use the maintainers corner to delete docs and request a rebuild and it works!