Hello,

I was talking about the user manual.   I imagine that the situation I was in is quite common---you've just implemented some small feature, and you want to write some documentation about it.  While working on the documentation, I want to rebuild the manual quickly, so that I can see what it looks like, and make sure that links etc.

So I think it would be very important for Hadrian to have some high-level targets equivalent to the current `make html` etc. rather than having to ask it to rebuild a specific file somewhere in the build tree.

The confusion with my previous e-mail was caused because I hadn't realized what happens when building the documentation is disabled, namely:
    1. There are multiple places to check if the documentation is actually disabled
    2. When the documentation is disabled, the build targets disappear, rather than change their behavior to say "Docs are disabled, I am not going to build them, do X if you want them build".

So the issue is more of a usability one. 

After I sent the e-mail to the list I realized that this all is documented online, so that's nice at least, but---in general---I think it would be nice if we could avoid such surprised, rather than having to document them in a separate place.

-Iavor






On Wed, Nov 1, 2017 at 11:07 AM Patrick Dougherty <patrick.doc@ameritech.net> wrote:
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@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@microsoft.com]
Sent: 01 November 2017 08:28
To: Iavor Diatchki <iavor.diatchki@gmail.com>; ghc-devs@haskell.org; Andrey Mokhov <andrey.mokhov@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@haskell.org] On Behalf Of Iavor Diatchki
Sent: 31 October 2017 21:49
To: ghc-devs@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@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@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs