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

`stack haddock` should always return location of index.html #781

Closed
dbaynard opened this Issue Aug 13, 2015 · 11 comments

Comments

Projects
None yet
7 participants
@dbaynard
Contributor

dbaynard commented Aug 13, 2015

Hello,

I propose that stack haddock always finishes by printing the location of the index.html file.

It can be inconvenient tracking down the documentation produced by stack haddock while developing a package.

When the command produces documentation, the last line of the output is

Generating Haddock index in
/home/<user>/<projectDirectory>/.stack-work/install/<arch>/<resolver>/<compilerVersion>/doc/index.html

The last line would be useful when there is no new documentation generated.


Steps to reproduce:

  1. Run stack haddock
  2. Run stack haddock

Expected:

The second run produces something like

The Haddock index is already up to date in
/home/<user>/<projectDirectory>/.stack-work/install/<arch>/<resolver>/<compilerVersion>/doc/index.html

Actual:

The command prints nothing.


Here is the stack --version output

$ stack --version
Version 0.1.2.0

Here is the command I ran with --verbose

$ stack haddock --verbose
Version 0.1.2.0
<date> <time>: [debug] Checking for project config at: /home/<user>/<projectDirectory>/stack.yaml @(stack_B8v5I05cffp30g7yBizAuN:Stack.Config src/Stack/Config.hs:496:9)
<date> <time>: [debug] Loading project config file stack.yaml @(stack_B8v5I05cffp30g7yBizAuN:Stack.Config src/Stack/Config.hs:519:13)
<date> <time>: [debug] Run process: ghc --info @(stack_B8v5I05cffp30g7yBizAuN:System.Process.Read src/System/Process/Read.hs:254:3)
<date> <time>: [debug] Run process: ghc --numeric-version @(stack_B8v5I05cffp30g7yBizAuN:System.Process.Read src/System/Process/Read.hs:254:3)
<date> <time>: [debug] Run process: ghc-pkg --no-user-package-db field --simple-output Cabal id @(stack_B8v5I05cffp30g7yBizAuN:System.Process.Read src/System/Process/Read.hs:254:3)
<date> <time>: [debug] Run process: ghc-pkg --no-user-package-db list --global @(stack_B8v5I05cffp30g7yBizAuN:System.Process.Read src/System/Process/Read.hs:254:3)
<date> <time>: [debug] Run process: ghc-pkg --global --no-user-package-db dump --expand-pkgroot @(stack_B8v5I05cffp30g7yBizAuN:System.Process.Read src/System/Process/Read.hs:254:3)
<date> <time>: [debug] Run process: ghc-pkg --user --no-user-package-db --package-db /home/<user>/.stack/snapshots/<arch>/<resolver>/<compilerVersion>/pkgdb/ dump --expand-pkgroot @(stack_B8v5I05cffp30g7yBizAuN:System.Process.Read src/System/Process/Read.hs:254:3)
<date> <time>: [debug] Run process: ghc-pkg --user --no-user-package-db --package-db /home/<user>/<projectDirectory>/.stack-work/install/<arch>/<resolver>/<compilerVersion>/pkgdb/ dump --expand-pkgroot @(stack_B8v5I05cffp30g7yBizAuN:System.Process.Read src/System/Process/Read.hs:254:3)
<date> <time>: [debug] Run process: ghc-pkg --no-user-package-db list --global @(stack_B8v5I05cffp30g7yBizAuN:System.Process.Read src/System/Process/Read.hs:254:3)

@dbaynard dbaynard changed the title from `stack haddock` should always return location of index.html (Enhancement) to `stack haddock` should always return location of index.html Aug 13, 2015

@borsboom borsboom added this to the 0.3.0.0 milestone Aug 13, 2015

@borsboom

This comment has been minimized.

Contributor

borsboom commented Aug 13, 2015

Yeah, that makes sense. I wonder if it should show the locations of all three indices (stack version 0.1.3.1 also generates an index that includes all dependencies, as well as one for all snapshot packages ever installed). A pull request would certainly be welcome.

@dbaynard

This comment has been minimized.

Contributor

dbaynard commented Aug 13, 2015

OK, I'll see what other responses this gets first.

@mgsloan

This comment has been minimized.

Collaborator

mgsloan commented Aug 14, 2015

Good point!

Along with always outputting the filepath, it would be good to ensure that this, and similar outputs, always come at the end of the build. For example, I'd be quite surprised if stack build --test --coverage --haddock always finished by yielding the URLs of both the haddock index and coverage index.

@elliottt

This comment has been minimized.

elliottt commented Feb 23, 2016

This would be really nice! It's handy that stack prints it out the first time, but it's not exactly a memorable path :)

@sjakobi

This comment has been minimized.

Contributor

sjakobi commented Jul 13, 2016

I think this is less important now that there's stack haddock --open, so I'm adjusting the priority.

@sjakobi sjakobi modified the milestones: P3: Optional, P2: Should Jul 13, 2016

@dbaynard

This comment has been minimized.

Contributor

dbaynard commented Aug 5, 2016

Re: stack haddock --open
: This doesn't work if running remotely, on a headless server.

However, given the stack path command exists I'd be happy to change this to a documentation issue; i.e. Give an example of serving the haddock documentation locally.

@mgsloan

This comment has been minimized.

Collaborator

mgsloan commented Aug 5, 2016

I'd prefer to keep it an implementation change. The less caveats that need to be documented, the better!

@alexanderkjeldaas

This comment has been minimized.

Contributor

alexanderkjeldaas commented Jul 28, 2017

I can't see the resolved behavior - neither in stack 1.4 nor stack 1.5. My command will dump some haddock warnings and nothing more.

I don't know if it fails - maybe that's why it doesn't write any output, but if so it should say that instead of being silent.

@AndreasPK

This comment has been minimized.

Contributor

AndreasPK commented Jul 28, 2017

For me on stack 1.5/Win10:

  • When the project is up to date I get the paths
  • When the project is not up to date I get the build log and paths
  • When the build fails I get an error message like Process exited with code: ExitFailure 1

So as it is I can't reproduce your problem. If you are sure the Paths don't show up while haddock/build does succeed please post OS, Console Log and a project on which it happens so I can take a look.

@alexanderkjeldaas

This comment has been minimized.

Contributor

alexanderkjeldaas commented Aug 2, 2017

No, the paths don't show up when haddock fails, but whether haddock succeeds or not is not apparent. I think either the url should be printed anyways, or some "last message" saying why it's not provided (the haddock build failed) should be printed.

@AndreasPK

This comment has been minimized.

Contributor

AndreasPK commented Aug 2, 2017

I think either the url should be printed anyways or ...

When would printing the expected URL after a failed haddock call be useful?

  • If there is no documentation because of the failure the link will lead to a non existing file
  • If the documentation is up to date already haddock shouldn't have been called to begin with
  • If there is out of date/incomplete documentation at the given path it introduces ambiguity since the given link might contain false/outdated information.

Personally I don't see much value in printing it in any of these cases.

Improving the feedback to make it clearer that haddock failed is a good idea but doesn't really match this issue imo so if you want to make that feature request it would be better to open a new Issue.

Also for me Process exited with code: ExitFailure 1 shows up when haddock fails and that is a pretty strong tell although it could be improved. But as above that would be another issue.

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