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.

Sign up for GitHub

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

Jump to bottom

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
@borsboom
Milestone
P1: Must

Comments

@UnkindPartition
Copy link
Contributor

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 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 commented Jun 1, 2015

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

@taladar
Copy link

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

@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

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

@borsboom
Copy link
Contributor

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

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 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

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

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

@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 commented Jun 15, 2015

just updated my opinion with more arguments and clarity

@borsboom
Copy link
Contributor

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

borsboom added a commit that referenced this issue Jun 19, 2015
@borsboom
Build haddocks for dependencies (#143)
d9acdfe
@borsboom borsboom mentioned this issue Jun 20, 2015
Merged
snoyberg added a commit that referenced this issue Jun 21, 2015
@snoyberg
Merge pull request #362 from commercialhaskell/143-haddock-deps
b90df3d 
Build haddocks for dependencies (#143)
borsboom added a commit that referenced this issue Jun 21, 2015
@borsboom
Generate Haddock index/contents for local packages (#143)
2b2ffb7
borsboom added a commit that referenced this issue Jun 22, 2015
@borsboom
Rename --deps-haddock arg to --haddock-deps (#143)
a6b2b7a
@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
Add Path.IO.copyDirectoryRecursive (#143)
410ff24
borsboom added a commit that referenced this issue Jun 22, 2015
@borsboom
Add Stack.GhcPkg.findGhcPkgDepends and findGhcPkgHaddockHtml (#143)
2f3fb70
borsboom added a commit that referenced this issue Jun 22, 2015
@borsboom
Haddock: use relative links and copy dependencies' docs (#143)
297dca5
borsboom added a commit that referenced this issue Jun 22, 2015
@borsboom
Normalise haddock-html paths before parsing (#143)
4f49c94 
Fixes error seen on Windows.
borsboom added a commit that referenced this issue Jun 22, 2015
@borsboom
Fix haddock output interleaving with sticky log (#143)
a0c4f3c
@snoyberg
Copy link
Contributor

snoyberg commented Jul 2, 2015

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

@snoyberg snoyberg closed this as completed Jul 2, 2015
borsboom added a commit that referenced this issue Jul 20, 2015
@borsboom
Generate indexes for all deps and all installed snapshot packages (#143)
907736b
dysinger added a commit that referenced this issue Jul 21, 2015
@dysinger
Merge branch 'master' into package-signing-with-gpg-and-git
1ad7487 
* 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
Assignees

@borsboom borsboom

Labels
None yet
Projects
None yet
Milestone
P1: Must
Development

No branches or pull requests
6 participants
@chrisdone @taladar @UnkindPartition @snoyberg @rvion @borsboom