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

A command `stack docs` that opens the locally installed documentation of packages? #1396

Closed
sjakobi opened this Issue Nov 21, 2015 · 11 comments

Comments

Projects
None yet
5 participants
@sjakobi
Contributor

sjakobi commented Nov 21, 2015

For example, from inside the current stack project:

  • stack docs Cabal opens
    ~/.stack/snapshots/x86_64-linux/lts-3.14/7.10.2/doc/Cabal-1.22.4.0/index.html
  • stack --stack-yaml stack-7.8.yaml docs Cabal opens
    ~/.stack/snapshots/x86_64-linux/lts-2.22/7.8.4/doc/Cabal-1.18.1.5/index.html

Given that stack already installs the documentation for ghc and haddock together with the binaries, stack docs could also open these. There needs to be a way to distinguish between the library documentation for haddock and the user guide though.

@sjakobi

This comment has been minimized.

Contributor

sjakobi commented Nov 21, 2015

On second thought, maybe stack haddock --open [PACKAGE] would be enough.

Without the [PACKAGE] argument I'd like the following behaviour:

  • When inside a project, open project/.stack-work/install/<platform/<snapshot>/<ghc-version>/doc/all/index.html.
  • Else, open ~/.stack/snapshots/<platform>/<global snapshot>/<ghc-version>/doc/index.html.
@mgsloan

This comment has been minimized.

Collaborator

mgsloan commented Nov 22, 2015

Sounds like a good idea to me! One tricky thing is what command to use for the browser. I suppose this could be part of .stack/config.yaml, and have it auto-try things like sensible-browser and xdg-open.

How about a --url option which makes it just put the URL to stdout instead of opening a browser.

On second thought, maybe stack haddock --open [PACKAGE] would be enough.

stack haddock is a synonym for stack build --haddock, so I'd prefer a new stack docs command.

@borsboom

This comment has been minimized.

Contributor

borsboom commented Nov 22, 2015

Sounds good to me as well. A pull request would be welcome.

@borsboom borsboom added this to the P3: Optional milestone Nov 22, 2015

@borsboom

This comment has been minimized.

Contributor

borsboom commented Nov 22, 2015

One problem with stack docs is that it conflicts with the stack doc command suggested in #1395. Making --open a build option, as originally suggested, might not be so bad; then running stack haddock --open <PACKAGE> would build the package's haddocks and then open them.

@borsboom

This comment has been minimized.

Contributor

borsboom commented Nov 22, 2015

have it auto-try things like sensible-browser and xdg-open.

If there isn't already a package on Hackage that provides cross-platform support for opening a browser, one should be created for this issue.

@yamadapc

This comment has been minimized.

Contributor

yamadapc commented Nov 26, 2015

If there isn't already a package on Hackage that provides cross-platform support for opening a browser, one should be created for this issue.

Node.js has it's open package on NPM (https://www.npmjs.com/package/open). At almost 1 million monthly downloads I'd say it could be a good source for inspiration.

There's an open-browser package on Hackage (https://hackage.haskell.org/package/open-browser) which seems to have support for xdg-open, open and Windows and should work fine for this. node-open bundles xdg-open on the repository for some reason.

@mstksg

This comment has been minimized.

mstksg commented Jan 16, 2016

Was wondering if you all think it'd be viable to have functionality similar to yard, where a command would run a local http server on a given port. This is nice because:

  1. People who develop on remote servers can have a browser on their own machine open and just refresh whenever changes happen.
  2. Not having to worry about what web browser to use; user opens the browser themselves at the beginning of their session and points to the local port.

I'm planning on implementing this myself, but I was wondering if anyone here had any comments on this (maybe this is already done/implemented? does it even belong in stack?); opening a new PR might be a bit noisy, as this concept is so closely tied to this one :)

@mgsloan

This comment has been minimized.

Collaborator

mgsloan commented Jan 18, 2016

@mstksg To me, that's a bit beyond the scope of stack. Certainly not a bad idea, though! Might be a good fit for a plugin, like stack-run

@mstksg

This comment has been minimized.

mstksg commented Jan 19, 2016

@mgsloan thanks, i definitely agree, once you put it that way!

@mgsloan

This comment has been minimized.

Collaborator

mgsloan commented Mar 23, 2016

@sjakobi describes how the behavior for this command should be in this PR comment. I'm mentioning this, because I'm closing out the PR due to lack of activity. Also note that that PR is a good starting point.

sjakobi added a commit to sjakobi/stack that referenced this issue Apr 4, 2016

@sjakobi sjakobi self-assigned this Apr 4, 2016

sjakobi added a commit to sjakobi/stack that referenced this issue Apr 4, 2016

sjakobi added a commit to sjakobi/stack that referenced this issue Apr 9, 2016

sjakobi added a commit to sjakobi/stack that referenced this issue Apr 9, 2016

sjakobi added a commit to sjakobi/stack that referenced this issue Apr 11, 2016

mgsloan added a commit that referenced this issue Apr 12, 2016

@sjakobi

This comment has been minimized.

Contributor

sjakobi commented Apr 12, 2016

Basic implementation in #2015, ideas for improvement in #2025.

@sjakobi sjakobi closed this Apr 12, 2016

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment