stack haddock should always return location of index.html

[dbaynard]

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)

[borsboom]

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]

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

[mgsloan]

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 would be really nice! It's handy that stack prints it out the first time, but it's not exactly a memorable path :)

[sjakobi]

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

[dbaynard]

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]

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

[alexanderkjeldaas]

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]

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]

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]

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.