How to build Haddock documentation quickly?

[Norman Ramsey]

 > Hi Norman,
 > 
 > Could you see if the command-line described here is of any help?
 > https://gitlab.haskell.org/ghc/ghc/-/issues/17929#building-the-docs
 > 
 > Particularly the "--freeze1 --flavour=Quick" bit.

It was reasonably fast, but it doesn't build the documentation I'm
interested in.  The file I wish to rebuild is

  _build/docs/html/libraries/ghc/GHC-Tc-Gen-Foreign.html

and the command recommended there is 

  hadrian/build -j --freeze1 --flavour=Quick _build/docs/html/libraries/base/base.haddock

Just adding `--freeze= --flavour=Quick` to my original command may
have helped a little; after editing GHC/Tc/Gen/Foreign.hs, my build
time was reduced to 3 minutes 11 seconds.  

I also took a flyer on these two commands:

   hadrian/build -j --freeze1 --flavour=Quick _build/docs/html/libraries/ghc/GHC-Tc-Gen-Foreign.html

   hadrian/build -j _build/docs/html/libraries/ghc/GHC-Tc-Gen-Foreign.html

But neither of these commands rebuilt the file.

I also tried

   hadrian/build -j --freeze1 --flavour=Quick --docs=no-sphinx docs

which succeeded but took 3 minutes 18 seconds.


I'm more than willing to dive into Hadrian and figure out how it works.
I could even add a new target to build just what I'm interested in.
But I would need help.  I've spent some time poking around the `doc`
directory, and I've read the Shake papers (and some of Andrei's work)
but I've never used these tools myself.  I got as far as
$GHC/hadrian/src/Rules/Documentation.hs, which led me to try the
`docs-haddock` target, and I got a slightly better result:
the document is rebuilt in 2 minutes 30 seconds.

There has to be a better way.  I suppose I could try to come up with a
set of options to `haddock` and to run it directly.  But maybe someone
can suggest another idea?

Is there a command-line option to Hadrian that will get it to show
every external command ("builder"?) as it is executed?


Norman


 > Le 18/11/2021 à 21:06, Norman Ramsey a écrit :
 > > In service of #20528, I'm trying to clean up some Haddock
 > > documentation in the GHC sources.  The only command I know is
 > >
 > >    ./hadrian/build -j _build/docs/html/index.html
 > >
 > > It turns out that if I change Haddock comments in one file
 > > (GHC/Tc/Gen/Foreign.hs), rebuilding the HTML takes a minute
 > > and a quarter.  That's a little long.  (And I had one build
 > > take over four minutes, which is even longer.)
 > >
 > > What tricks can I use to speed up this process?  Might there be a way
 > > to run Haddock directly until things are to my liking?