Hadrian: introduce ways to skip some documentation targets

The initial motivation for this is to have a chance to run the binary
distribution rules in our Windows CI without having to install
sphinx-build and xelatex there, while retaining the ability to
generate haddocks. I just ended up extending this idea a little bit so
as to have control over whether we build haddocks, (sphinx) HTML manuals,
(sphinx) PDF manuals and (sphinx) manpages.

2 files changed, 59 insertions, 1 deletions

diff --git a/hadrian/doc/make.md b/hadrian/doc/make.md
index 0d9bb911b4..15bd6bd799 100644
--- a/hadrian/doc/make.md
+++ b/hadrian/doc/make.md
@@ -174,6 +174,22 @@ time you fire up a build. This is not possible with the Make build system.
   build docs
   ```
 
+- Build documentation, but without haddocks (resp. without HTML or PDF manuals)
+
+  ``` sh
+  # Make
+  echo 'HADDOCKS_DOCS = NO' > mk/build.mk
+  # For HTML manuals: BUILD_SPHINX_HTML = NO
+  # For PDF manuals: BUILD_SPHINX_PDF = NO
+  make
+
+  # Hadrian
+  build docs --docs=no-haddocks
+  # Append --docs=no-sphinx-pdfs, --docs=no-sphinx-html or
+  # --docs=no-sphinx-man (or --docs=no-sphinx to encompass them all)
+  # to further reduce or even completely disable documentation targets.
+  ```
+
 - Running nofib
 
   ``` sh
diff --git a/hadrian/doc/user-settings.md b/hadrian/doc/user-settings.md
index b997cd977f..68929d325a 100644
--- a/hadrian/doc/user-settings.md
+++ b/hadrian/doc/user-settings.md
@@ -32,7 +32,10 @@ data Flavour = Flavour {
     -- | Build profiled GHC.
     ghcProfiled :: Bool,
     -- | Build GHC with debug information.
-    ghcDebugged :: Bool }
+    ghcDebugged :: Bool
+    -- | Whether to build docs and which ones
+    --   (haddocks, user manual, haddock manual)
+    ghcDocs :: Action DocTargets }
 ```
 Hadrian provides several built-in flavours (`default`, `quick`, and a few
 others; see `hadrian/doc/flavours.md`), which can be activated from the command line,
@@ -231,6 +234,45 @@ verboseCommand = output "//rts/sm/*" &&^ way threaded
 verboseCommand = return True
 ```
 
+## Documentation
+
+`Flavour`'s `ghcDocs :: Action DocTargets` field lets you
+customize the "groups" of documentation targets that should
+run when running `build docs` (or, transitively,
+`build binary-dist`).
+
+```haskell
+type DocTargets = Set DocTarget
+data DocTarget = Haddocks | SphinxHTML | SphinxPDFs | SphinxMan
+```
+
+By default, `ghcDocs` contains all of them and `build docs` would
+therefore attempt to build all the haddocks, manuals and manpages.
+If, for some reason (e.g no easy way to install `sphinx-build` or
+`xelatex` on your system), you're just interested in building the
+haddocks, you could define a custom flavour as follows:
+
+```haskell
+justHaddocksFlavour :: Flavour
+justHaddocksFlavour = defaultFlavour
+    { name = "default-haddocks"
+	, ghcDocs = Set.singleton Haddocks }
+```
+
+and then run `build --flavour=default-haddocks`. Alternatively,
+you can use the `--docs` CLI flag to selectively disable some or
+all of the documentation targets:
+
+- `--docs=none`: don't build any docs
+- `--docs=no-haddocks`: don't build haddocks
+- `--docs=no-sphinx`: don't build any user manual or manpage
+- `--docs=no-sphinx-html`: don't build HTML versions of manuals
+- `--docs=no-sphinx-pdfs`: don't build PDF versions of manuals
+- `--docs=no-sphinx-man`: don't build the manpage
+
+You can pass several `--docs=...` flags, Hadrian will combine
+their effects.
+
 ## Miscellaneous
 
 To change the default behaviour of Hadrian with respect to building split