Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Build haddocks for dependencies #143

Closed
UnkindPartition opened this issue Jun 1, 2015 · 14 comments
Closed

Build haddocks for dependencies #143

UnkindPartition opened this issue Jun 1, 2015 · 14 comments
Assignees
Milestone

Comments

@UnkindPartition
Copy link
Contributor

@UnkindPartition UnkindPartition commented Jun 1, 2015

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
Copy link
Contributor

@snoyberg snoyberg commented Jun 1, 2015

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

@snoyberg snoyberg added this to the Third release milestone Jun 1, 2015
@borsboom
Copy link
Contributor

@borsboom borsboom commented Jun 1, 2015

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

@taladar
Copy link

@taladar taladar commented Jun 9, 2015

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
Copy link
Contributor

@borsboom borsboom commented Jun 15, 2015

@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
Copy link
Member

@chrisdone chrisdone commented Jun 15, 2015

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

@borsboom
Copy link
Contributor

@borsboom borsboom commented Jun 15, 2015

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
Copy link
Contributor

@borsboom borsboom commented Jun 15, 2015

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
Copy link
Contributor

@rvion rvion commented Jun 15, 2015

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 👍

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
Copy link
Member

@chrisdone chrisdone commented Jun 15, 2015

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
Copy link
Contributor

@borsboom borsboom commented Jun 15, 2015

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
Copy link
Contributor

@borsboom borsboom commented Jun 15, 2015

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

@rvion
Copy link
Contributor

@rvion rvion commented Jun 15, 2015

just updated my opinion with more arguments and clarity

@borsboom
Copy link
Contributor

@borsboom borsboom commented Jun 15, 2015

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

borsboom added a commit that referenced this issue Jun 19, 2015
snoyberg added a commit that referenced this issue Jun 21, 2015
Build haddocks for dependencies (#143)
borsboom added a commit that referenced this issue Jun 21, 2015
borsboom added a commit that referenced this issue Jun 22, 2015
@snoyberg snoyberg modified the milestones: 0.1.0.0, 0.2.0.0 Jun 22, 2015
borsboom added a commit that referenced this issue Jun 22, 2015
borsboom added a commit that referenced this issue Jun 22, 2015
borsboom added a commit that referenced this issue Jun 22, 2015
@snoyberg
Copy link
Contributor

@snoyberg snoyberg commented Jul 2, 2015

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

@snoyberg snoyberg closed this Jul 2, 2015
borsboom added a commit that referenced this issue Jul 20, 2015
dysinger added a commit that referenced this issue Jul 21, 2015
* master:
  Generate indexes for all deps and all installed snapshot packages (#143)
  Move windows-only failure in Stack.Iface to runtime instead of compile time
  Set lower dependency restrictions on project-template.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
6 participants