search

snowleopard / hadrian

Hadrian: a new build system for the Glasgow Haskell Compiler. Now merged into the GHC tree!
https://gitlab.haskell.org/ghc/ghc/tree/master/hadrian
MIT License
208 stars 37 forks source link

Documentation broken by upstream Haddock change #492

Closed patrickdoc closed 6 years ago

patrickdoc commented 6 years ago

Haddock commit https://github.com/haskell/haddock/commit/e99aefb broke Hadrian's ability to generate the documentation. In particular, the file haddock-util.js was removed from the repository. That file is currently being used as the target of need, which causes documentation to break.

https://github.com/snowleopard/hadrian/blob/7d2368d714c7ed3fb8c096882564575aacf2b396/src/Rules/Documentation.hs#L120-L121

https://github.com/snowleopard/hadrian/blob/7d2368d714c7ed3fb8c096882564575aacf2b396/src/Rules/Documentation.hs#L137-L141

Haddock uses all the files in that folder to generate and style the web pages. It contains both style themes and JavaScript for functionality. Because Haddock requires that folder to run (the wrapper script explicitly names it), I propose copying it when Haddock is built rather than needing it when building the documentation.

The fastest solution is to just point haddockHtmlLib at a different file, but that feels a little brittle to me.

snowleopard commented 6 years ago

@patrickdoc Thank you for reporting this!

If haddock-util.js was removed, does it mean it is no longer needed to build docs? If it is still needed, how does Make build docs without it?

patrickdoc commented 6 years ago

Make copies the entire utils/haddock/haddock-api/resources folder to inplace/lib. It doesn't check for anything inside that folder.

haddock-util.js was removed because they changed the code to be compiled from TypeScript and combined some files. So the contents of the folder are still needed, but that particular file doesn't exist.

snowleopard commented 6 years ago

@patrickdoc I see, thank you.

I am travelling at the moment, so not sure when I'll have time to look at this, but happy to review a PR if anyone is up to trying to fix this. Presumably, it's an easy fix.

snowleopard commented 6 years ago

@patrickdoc I've fixed this by switching to stamp file inplace/lib/html/README.md. I agree with you that this is fragile, so I've added a couple of TODOs to hopefully improve this in future.