Building the docs, again

Wed Nov 1 18:22:24 UTC 2017

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 at 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 at newcastle.ac.uk
> <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
> <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
> <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
> <https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fghc.mk&data=02%7C01%7Csimonpj%40microsoft.com%7Cf681d88b258e48157e2008d520a95302%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C636450833981966485&sdata=qPWSl5FMtQ%2FRzTI8PYxHfkK%2B%2FltgBh2z1VRr8dJleok%3D&reserved=0>
> 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
> <https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fghc.mk&data=02%7C01%7Csimonpj%40microsoft.com%7Cf681d88b258e48157e2008d520a95302%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C636450833981966485&sdata=qPWSl5FMtQ%2FRzTI8PYxHfkK%2B%2FltgBh2z1VRr8dJleok%3D&reserved=0>
> 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
> <https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fconfig.mk&data=02%7C01%7Csimonpj%40microsoft.com%7Cf681d88b258e48157e2008d520a95302%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C636450833981966485&sdata=F9gkJnWKkFVjF0ZgraTEyQXPnOA4Id2lL7jhppN1mrc%3D&reserved=0>`
> 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/0fefd8e1/attachment.html>