Cabal: Implement 'cabal upload --haddock'

[23Skidoo]

See this comment. Uploading locally-built Haddock documentation to Hackage is a common use case, and we should support it directly.

[bitemyapp]

@23Skidoo part of the objective with this is to not only handle the uploading of the haddocks, but have the html-location and content-location set correctly, right?

[23Skidoo]

@bitemyapp Right.

[bennofs]

I would like to work on this. However, I had the following design in mind:

1. add a new option to cabal sdist: use --doc to generate a documentation tarball.
2. add a new option to cabal upload: use --doc to upload a documentation tarball.
3. Perhaps allow cabal upload to be run without arguments (and cabal upload --doc), which will automatically generate sdists/documentation tarballs and upload them.

That way, upload's functionality stays constrained to uploading stuff to hackage and it's consistent with how uploading source tarballs works today. Also, I opted for cabal sdist --doc instead of cabal haddock --for-hackage since the latter would clobber existing documentation in dist/doc, which users still might want to use for development (and that documentation then of course shouldn't refer to the hackage links).

Would that design be ok?

[bennofs]

Now, after looking at the code some more, I'm still not exactly sure where all the parts for this fit. I think there are three parts:

1. generate the documentation with links etc suitable for hackage upload. This now looks like it would fit best into the haddock command, in Cabal-the-library.
2. from that, generate a documentation tarball. This must be done in cabal-install, since only that may depend on the library required for generating tarballs.
3. upload a documentation tarball. This should go in cabal upload, provided by cabal-install.

I'm reasonably sure about 1 and 3, but I don't know what to do about 2. Should it be part of cabal sdist? (since that already deals with creating temporary directories and creating archives from them). Or rather a special, cabal-install only, flag for cabal haddock?

[23Skidoo]

@bennofs I'd say that 2 should also be a part of cabal haddock, and I think you should reuse the --for-hackage option for this. The workflow would then be:

$ cabal haddock --for-hackage
$ cabal upload --doc

Having to remember to call cabal sdist in between is too complicated, IMO. Also, cabal upload --doc should invoke cabal haddock --for-hackage if there's no existing documentation tarball (ideally, it'd also look at source timestamps and regenerate it if needed, but that can be a future improvement).

[bitemyapp]

I agree with the UX improvements @23Skidoo has laid out here. The program should understand the intent of the user and just make it happen.

[bennofs]

Ok, that sounds reasonable.

[bennofs]

So I've implemented cabal haddock --for-hackage now (including the .tar.gz creation), but again I'm hitting UX issues when implementing cabal upload --doc:

1. cabal upload supports multiple arguments. What should cabal upload foo-1.2.tar.gz bar-2.3.tar.gz qux-2.4-docs.tar.gz do?
2. If we decide that (1) shoud upload packages for foo-1.2, bar-2.3 and upload docs for qux-2.4, then what should cabal upload --doc foo-1.2.tar.gz bar-2.3.tar.gz qux-2.4-docs.tar.gz do?

(I'll be away for a week, so I won't be able to respond for one week)

[23Skidoo]

I think that plain cabal upload should only upload packages, and cabal upload --doc should only upload docs. Allowing to mix the two complicates the UI and implementation, and I don't think that the multi-argument form will be used that often anyway.

[ttuegel]

I think that plain cabal upload should only upload packages, and cabal upload --doc should only upload docs. Allowing to mix the two complicates the UI and implementation, and I don't think that the multi-argument form will be used that often anyway.

This is absolutely wrong. Given that we haven't had reliable documentation building on Hackage in many _years_, and given that packages with external dependencies can't be built on Hackage anyway, the default behavior of cabal upload should be to do the right thing and upload documentation, too. We can add --only-package and --only-doc to support these corner cases.