Building the docs, again

[Patrick Dougherty]

I spent some time with the docs this summer, and wrote a fair bit of the Hadrian documentation building code. So maybe I can shed some light.

The question is which docs do you want to build? The library documentation relies on the haddock executable, which is one of the last targets in the entire build. Also, IIRC, creating the nice links and references is somewhat tangled up with actually building the libraries. So it's not possible to avoid building GHC if you want the haddocks.

On the other hand, you can build just the user's guide using Hadrian. You can build any sphinx html target like this:

../build.sh _build/docs/html/users_guide/index.html

Or pdf with:

../build.sh _build/docs/pdfs/users_guide.pdf

While not the cleanest, it does work. So, I think the only way you can skip building GHC is using Hadrian for sphinx targets.

Until recently, the users guide did depend on building all of GHC. I believe the make-based build just doesn't know about this change? I think I looked into updating it, but determined that it would be easier just to update Hadrian instead. I'm a little foggy on the details at this point. 

Best,
Patrick

> On Nov 1, 2017, at 7:13 AM, Andrey Mokhov <andrey.mokhov at newcastle.ac.uk> wrote:
> 
> > Maybe Hadrian will help here?
>  
> Hadrian can build documentation in various formats but the current implementation is very coarse-grain: we either build all possible docs or no docs at all. It would be relatively easy to add more fine-grain documentation targets and modes. If someone could design/describe the requirements in a ticket that would be great.
>  
> Cheers,
> Andrey
>  
>  
> From: Simon Peyton Jones [mailto:simonpj at microsoft.com] 
> Sent: 01 November 2017 08:28
> To: Iavor Diatchki <iavor.diatchki at gmail.com>; ghc-devs at haskell.org; Andrey Mokhov <andrey.mokhov at newcastle.ac.uk>
> Subject: RE: Building the docs, again
>  
> It is quite confusing that we can be setting the same variable to different values in different places.   It would also be quite helpful if we modified the Makefile to say `documentation build target is disabled` or some such, rather then going ahead and building the whole of GHC, only at the end to inform me that it doesn't know what is `html`. 
> 
> Maybe Hadrian will help here?
>  
> Simon
>  
> From: ghc-devs [mailto:ghc-devs-bounces at haskell.org] On Behalf Of Iavor Diatchki
> Sent: 31 October 2017 21:49
> To: ghc-devs at haskell.org
> Subject: Re: Building the docs, again
>  
> Hello,
> 
>  
> 
> never mind, I figured it out---apparently the build targets were disabled for the `quick` flavor, which I was using. 
> 
>  
> 
> It is quite confusing that we can be setting the same variable to different values in different places.   It would also be quite helpful if we modified the Makefile to say `documentation build target is disabled` or some such, rather then going ahead and building the whole of GHC, only at the end to inform me that it doesn't know what is `html`. 
> 
>  
> 
> -Iavor
> 
>  
> 
>  
> 
>  
> 
> On Tue, Oct 31, 2017 at 2:26 PM Iavor Diatchki <iavor.diatchki at gmail.com> wrote:
> 
> Hello,
> 
>  
> 
> sometime ago, I asked if it is possible to build just the GHC docs, without building the compiler.  I was told to just run `make html`.  This does not appear to work, the command seems to just start building GHC.  What am I doing wrong?
> 
>  
> 
> Here is the output I see, running the command from the root of the GHC tree.
> 
>  
> 
> > make html V=0
> 
> ===--- building phase 0
> 
> make --no-print-directory -f ghc.mk phase=0 phase_0_builds
> 
> make[1]: Nothing to be done for 'phase_0_builds'.
> 
> ===--- building phase 1
> 
> make --no-print-directory -f ghc.mk phase=1 phase_1_builds
> 
>   HC [stage 0] compiler/stage1/build/BufWrite.o
> 
>   HC [stage 0] compiler/stage1/build/Pretty.o
> 
> compilation IS NOT required
> 
>   HC [stage 0] compiler/stage1/build/PprColour.o
> 
> compilation IS NOT required
> 
>   HC [stage 0] compiler/stage1/build/Outputable.o
> 
> compilation IS NOT required
> 
>   HC [stage 0] compiler/stage1/build/Json.o
> 
> compilation IS NOT required
> 
>   HC [stage 0] compiler/stage1/build/SrcLoc.o
> 
> compilation IS NOT required
> 
>   HC [stage 0] compiler/stage1/build/BasicTypes.o
> 
> compilation IS NOT required
> 
>   HC [stage 0] compiler/stage1/build/Unique.o
> 
>   HC [stage 0] compiler/stage1/build/Packages.o-boot
> 
> compilation IS NOT required
> 
>   HC [stage 0] compiler/stage1/build/FiniteMap.o
> 
> compilation IS NOT required
> 
>   HC [stage 0] compiler/stage1/build/Name.o-boot
> 
>  
> 
> (then I interrupted it).
> 
>  
> 
> Also, in `mk/config.mk` I see this:
> 
> BUILD_SPHINX_HTML        = YES
> 
>  
> 
> -Iavor
> 
>  
> 
>  
> 
>  
> 
> _______________________________________________
> ghc-devs mailing list
> ghc-devs at haskell.org
> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-devs/attachments/20171101/a0076e1e/attachment-0001.html>