Build haddocks for dependencies

[UnkindPartition]

From what I see, haddocks aren't built when installing dependencies.

It would be nice to support these use cases:

1. I only want to install an app and don't care about haddocks, don't waste my time
2. I have plenty of time, build haddocks while installing packages
3. I want to get started ASAP, so for now, only build the dependencies, but later I may want to run stack haddock and have it build the haddocks for the dependencies (without rebuilding them, of course). In other words, be able to build haddocks on demand.

[snoyberg]

@manny-fp I think you've done most of the Haddock work, what do you think about this?

[borsboom]

This makes sense to me (I'd like the same kinds of things).

[taladar]

It might also make sense to add an option to just build the Haddocks for local packages mentioned in stack.yaml? The use-case I have in mind would be to build documentation for locally developed code on a CI server and upload it somewhere.

[borsboom]

@taladar That's currently how stack haddock works and that option will definitely stay.

Question for everyone: should the default be to build haddocks for only local packages, or should the default be to build haddocks for all dependencies?

[chrisdone]

Good question, this is also relevant for providing an eventual stack hoogle.

[borsboom]

Another question: for dependencies installed in ~/.stack, we probably should put the haddocks there as well. When linking from docs for local packages to dependencies' docs, should we:

1. Use absolute file URLs (e.g. file:///home/user/.stack/doc/package/)
2. Use relative file URLs (e.g. ../../../.stack/doc/package/). This means links would break if you move your project directory.
3. Always have the links to ../package/, and create filesystem symlinks (or fallback to copies if symlinks not available) pointing to the actual location.

The same question also applies to linking to docs for the standard libraries included with GHC.

I lean toward (3), as this makes for consistent links and makes the documentation easy to copy to a web server or otherwise move around.

[borsboom]

And another question: should stack haddock also create a doc index for all packages by default? What should be included in the index?

1. Only local packages?
2. Combine local packages and dependencies?
3. Separate indices for local packages and dependencies?
4. Both (2) and (3)?

Also, would a "master index" containing all packages installed in ~/.stack (and those included with GHC) be useful?

[rvion]

q1

Question for everyone: should the default be to build haddocks for only local packages, or should the default be to build haddocks for all dependencies?

I think the default should be to build the doc for all dependecies

• Stack is primarilly for dev
• Easier future integration with ide related tool
• Easier to have the same full setup since size is not really a problem.
• Building the doc will help find bugs in haddocs, and is therefore a sanity check
• It is what I would expect as a user (package managers in other languages I know do so, and have a --no-doc flag somewhere)

q2

Another question: for dependencies installed in ~/.stack, we probably should put the haddocks there as well. When linking from docs for local packages to dependencies' docs, should we:

1. Use absolute file URLs (e.g. file:///home/user/.stack/doc/package/)
2. Use relative file URLs (e.g. ../../../.stack/doc/package/). This means links would break if you move your project directory.
3. Always have the links to ../package/, and create filesystem symlinks (or fallback to copies if symlinks not available) pointing to the actual location.

I vote for 3 ( links to ../package/) too because :

• ability to launch warp server to serve docs as you said,
• ability to mount the .stack server in various docker container with different user name
• portability is generally a good idea
• it is not too hard to because it fits well the current directory structure

q3

And another question: should stack haddock also create a doc index for all packages by default? What should be included in the index?

1. Only local packages?
2. Combine local packages and dependencies?
3. Separate indices for local packages and dependencies?
4. Both (2) and (3)?

I would lean toward 4. : both (2) and (3)

q4

Also, would a "master index" containing all packages installed in ~/.stack (and those included with GHC) be useful?

yes :+1:

Main vision around doc

• All docs generated unless said so
• Documentation folder is portable and links are all relative
• special index page link to both global and project-only doc.
• possibly a new stack documentation commands spawning a warp server for docs

[chrisdone]

Another question: for dependencies installed in ~/.stack, we probably should put the haddocks there as well. When linking from docs for local packages to dependencies' docs, should we:

Option 1 or 3 seems pretty good.

And another question: should stack haddock also create a doc index for all packages by default? What should be included in the index?

Under .stack-work, I take it? I'm not sure what should be in the index, it's not a use-case I'm used to having. The index here means that big module listing, right? I can see either being helpful.

[borsboom]

edit: this answered a different question, I thought @chrisdone was asking about the "master index" for all dependencies.

It would be under ~/.stack, since it would only be for non-local packages. It would basically give you one set of docs for every dependency you've ever used for any project.

In all this, I'm also thinking about optionally generating hoogle databases along the way, so I think the above would be especially useful for being able to hoogle a big set of packages locally. In the case of using a Docker image with all Stackage packages preinstalled, it would give you a way to locally hoogle all of Stackage.

[borsboom]

@chrisdone Oh sorry, I answered the wrong question there! To answer your actual question, YES, it would be in ~/.stack-work.

[rvion]

just updated my opinion with more arguments and clarity

[borsboom]

@rvion happy to say that we share basically the same vision

[snoyberg]

I believe this is fully implemented, closing. Please reopen otherwise.