@GrahamcOfBorg build cachix haskellPackages.servant haskellPackages.servant-docs haskellPackages.servant-server

Here's my arguments for completely removing this documentation (as opposed to continuing to bump the documentation hash):

1. The documentation hash has to be bumped every time a new version of servant comes out. In the past various people have done this. From looking through the git history, it appears that @Profpatsch added this documentation generation, and it has subsequently been bumped by @peti, @Izorkin, and @basvandijk,

   However, after a new servant release, it appears that this hash goes quite a long time without being fixed. There doesn't appear to be anybody actively maintaining this. Over the past few years, this hash appears to be broken significantly longer than it has actually been working.

2. If you enable the binary cache, you often don't realize this isn't working (because you get the documentation from the binary cache), but in that case you often get documentation from an old version of Servant. Given that the Servant API still occasionally has big changes, I imagine it would be quite confusing to get old documentation.

Given that there doesn't seem to be anyone actively keeping up with bumping this hash after every Servant release, and that having old documentation can be very confusing, I think it would be better to just completely remove the documentation generation as I have done in this PR.

If someone does feel strongly about providing this documentation from nixpkgs, I'd suggest creating a separate derivation that just contains the documentation. This could be maintained separately from haskellPackages.servant.

Is this documentation hard to be built? Or it is just a matter of updating a hash?

I find a bit sad to remove it. Can't we hardcode the doc version and assert that the hardocded version matches super.servant.version ? The doc could be made optional so that it doesn't break the build. Putting it in another derivation can be confusing: harder to find and is that a servant package or just the servant doc ?

@AndersonTorres

Is this documentation hard to be built? Or it is just a matter of updating a hash?

It is not hard to build the documentation. The code that I have removed in this PR is responsible for building the documentation. It is relatively straightforward.

The only hard part is keeping the hash updated. In #107858 (comment) I try to make the argument that since no one seems to be keeping this hash updated, we should just remove the documentation generation.

Although please keep in mind that there are two sets of documentation for Servant. There are the haddocks (https://hackage.haskell.org/package/servant-0.18.2/docs/Servant-API.html), as well as the tutorials site (https://docs.servant.dev/en/stable/cookbook/index.html).

This PR is removing the tutorials site, not the Haddocks.

Upstream doesn't distribute tutorials site along with the servant package, so I don't think it is too crazy that we wouldn't either.

@teto

Can't we hardcode the doc version and assert that the hardcoded version matches super.servant.version?

Yes, we could do that.

I think @maralorn tried something like that for some other derivations in haskellPackages, but he ended up removing it. Maybe it was annoying to always keep updated?

We definitely want servant to always be buildable in nixpkgs (because it is used by important tools like cachix), and I'm worried about increasing any friction in keeping it working.

If there was someone that reliably bumped this servant docs hash, I would be much less eager to remove it. However, in the past couple years, there hasn't been.

The doc could be made optional so that it doesn't break the build.

Hmm, I can't quite imagine how this would work. How would you go about writing something like this?

Putting it in another derivation can be confusing: harder to find and is that a servant package or just the servant doc?

I completely agree. Having the documentation be in a separate derivation would be more confusing.

However, my argument is that it would be worth it in order to reduce the maintenance burden. If we moved the documentation to a separate derivation, and then someone started always updating the hash in a timely manner, I would feel much better about adding the documentation back to the main haskellPackages.servant derivation.

(Another possibility would be restructuring the derivations in a way that the ryantm bot would do the updates for us. I'm not sure what would need to happen for this to work.)

I think @maralorn tried something like that for some other derivations in haskellPackages, but he ended up removing it. Maybe it was annoying to always keep updated?

I did stuff like that and it worked. The point is, that I have never done it as a permanent solution only as a temporary reminder as a "fix this once we can". I think putting asserts into the code to break eval on update is a great way to enforce timely action on an issue. But in reality this just means we write it on @peti s todo-list. I assume bumping this hash is around five minutes of work evry time. So this would only be worth it if people actually use this documentation. Do you still @Profpatsch? Because I am pretty sure I wouldn‘t even know about it and just look at it online.

An alternative would be to insert something in the doCheck phase that asserts the documentation and package versions match. That would be the cleaner approach. But it would break servant regularly. While noticing and fixing that would be slower, in theory it could have the benefit on not relying alone no petis intervention.

Merged in 4827826.