commercialhaskell / commercialhaskell/stack
stack haddock --haddock-for-hackage
- Dominant language
- Haskell
- Stars
- 4.1k
- Forks
- 850
- Avg merge
- 10h 37m
- Merged PRs (30d)
- 4
Description
I've spent the better part of two days trying to manually upload haddocks to Hackage (they won't build there due to a system library dependency). I've arrived at a state where:
- `stack haddock` can build complete, locally browse-able documentation successfully, but it cannot build in a way suitable for publishing to Hackage (if this is wrong, please-please correct me!)
- `cabal haddock` can build documentation meant for Hackage, but it cannot build my project's dependencies documentation (due to [a `quickjump`-related bug](https://github.com/haskell/haddock/issues/1582)) so what it publishes is missing effectively all links
Therefore, I would love to see `stack haddock` reach feature-parity with `cabal haddock --haddock-for-hackage`, so I could solve the first point and stop fighting with the second.
---
As far as I can tell, `--haddock-for-hackage` does a number of things. Some of them I could accomplish externally with the docs after `stack haddock` produces them, but others I cannot.
The things `cabal haddock --haddock-for-hackage` does, that I can't seem to make happen by any means are:
- The HTML has the correct "preamble" (e.g. Contents link goes back to the main page)
- Links to dependencies go to the correct on-Hackage locations (`/package/$pkg-$version`)
The things `cabal haddock --haddock-for-hackage` does, that I _could_ make happen externally, but ideally wouldn't have to are:
- A correctly-structured, and correctly compressed `--docs.tar.gz` file is created
- It must have a single, top-level directory `--docs` that contains only the package's docs
- It must be (if using GNU `tar`) compressed with `--format=ustar`
And lastly, `cabal upload --publish --documentation ` handles the authorized `PUT` to `/package/-/docs` to actually publish them, which is another thing I could handle externally, but would be ideal for `stack upload` to know how to do.
As mentioned, I've been fighting with this, so I have some details that might be useful for investigating this:
The `--haddock-for-hackage` option implies at least:
- `--haddock-hyperlinked-source`
- `--haddock-html-location='/package/$pkg-$version`
- `--haddock-content-location='/package/$pkg-$version`
- `--haddock-quickjump`
- `--haddock-preamble=?I'm not sure?`
It's hard to exactly trace through [the Cabal code](https://hackage.haskell.org/package/Cabal-3.10.1.0/docs/Distribution-Simple-Haddock.html#v:haddock), but the `--x-location` options are key, and are particularly hard (impossible?) for me to accomplish any way besides using `cabal haddock`, as it seems to end up interacting with an isolated package registry in order to locate the dependencies in order to construct by-dependency options to pass to `haddock` telling it where each thing is. In other words, `stack haddock` kind of has to do it for me.
Contributor guide
Assessment
This issue has not been assessed yet.