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

[sjakobi]

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]

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]

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]

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

[borsboom]

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]

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]

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]

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]

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

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

[mgsloan]

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

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