Fix #5210 Don't refer to index.html when Haddock will not create it

[mpilgrem]

Haddock documents that it will not create index.html if option --use-contents or option --use-index is passed to it. See: https://haskell-haddock.readthedocs.io/en/latest/invoking.html#cmdoption-use-contents

However, that is not reflected in the existing logic for result in Distribution.Simple.Haddock.renderArgs, resulting in the behaviour complained about in issue #5210. This pull request fixes that.

• Patches conform to the coding conventions. I have followed the style of the surrounding source code.
• Any changes that could be relevant to users have been recorded in the changelog. I don't think this fix merits a Change Log entry.
• The documentation has been updated, if necessary. The feature is undocumented, so there is no documentation to update.
• Manual QA notes have been included. I don't think QA notes are needed, but I have included a code comment.

[ulysses4ever]

Any chance for a test?

Changelog would be nice too.

[mpilgrem]

As requested, I've add something to Cabal's ChangeLog (I hope it was the correct file) and also to cabal-install's (as it flows through to the tool, too).

I can't think of how to test for the original mistake.

[geekosaur]

There's a changelog.d directory into which changelog fragments go, rather than edit the ChangeLog directly; this lets changelogs be built for a particular version from the commits that go into that version.

[ulysses4ever]

Thanks! The explanation about changelogs is referenced in the PR template.

[mpilgrem]

@geekosaur, @ulysses4ever apologies on ChangeLog. I've now read the instructions, and tried again.

[ulysses4ever]

For testing: could you create a copy of cabal-testsuite/PackageTests/NewHaddock/HaddockOutput/HaddockOutputCmd, rename it, change the call to cabal in cabal.test.hs from

  r <- cabal' "haddock" ["--haddock-output-dir=docs", "A"] 

to

  r <- cabal' "haddock" ["--haddock-output-dir=docs", " --haddock-for-hackage" "A"] 

and replace the last line in the same file (assertFindInFile...) with assertOutputDoesNotContain "index.html" r?

I may be missing some details but high-level this is the way to go, I think.

To test is locally you may need to dive into https://github.com/haskell/cabal/blob/master/cabal-testsuite/README.md Most importantly, --with-cabal should be set correctly (e.g. to $(cabal list-bin cabal) after you have built cabal).

[mpilgrem]

@ulysses4ever, I have added a test but my attempts to test the test locally came to naught, because Test.Cabal.Prelude.withRepo contains a skipIfWindows. So, I am relying on CI to test the test. EDIT: Well that did not work ... I am retrying with a simpler test. EDIT2: Well that did not work either. Perhaps it is something to do with the cabal.out file ... I am retrying with one.

[ulysses4ever]

Thank you for willing to give it a go, and I'm sorry it doesn't go through yet.

withRepo may actually be not necessary. You could try any other existing test that calls cabal against a local package instead of a dependency (withRepo is only necessary when a test package uses a dependency).

[ulysses4ever]

Sorry, didn't see the edits until now (better send new comments — for visibility). Yes, .out will need to be adjusted. Usually it's done by calling the test binary with --accept but if you can't run it locally, this may be a problem...

[mpilgrem]

@ulysses4ever, I finally arrived at a test that has passed the CI.

[ulysses4ever]

Terrific, thank you! Apologies for all the pain due to the test suite, but tests is the only way to assure sanity in the future..