ghc.withPackages: install documentation to -with-packages output

* Will make it so that GHC.Paths's docdir NIX_GHC_DOCDIR points to an
  actual directory.

* Documentation of all packages in the environment is available in
  `$out/share/doc`.

This has previously been attempted in NixOS#76842 and reverted in NixOS#77442,
since documentation can collide when the libraries wouldn't (thanks to
the hash in the lib filename). `symlinkJoin` allows collision, so this
solution should be akin to NixOS#77523 (minus `buildEnv`, one step at a
time). `installDocumentation = false` restores the old behavior.

Collision in the documentation only happen if the dependency closure of
the given packages has more than one different derivation for the same
library of the very same version. I'm personally inclined not to claim
that our infrastructure does anything sensible in this case.
Additionally, the documentation is likely largely the same in such
cases (unless it is heavily patched).

Resolves NixOS#150666.
Resolves NixOS#76837.
Closes NixOS#150968.
Closes NixOS#77523.

nixos/doc/manual/from_md/release-notes/rl-2305.section.xml

@@ -519,6 +519,17 @@
           <literal>nixos/modules/profiles/minimal.nix</literal> profile.
         </para>
       </listitem>
+      <listitem>
+        <para>
+          The <literal>ghcWithPackages</literal> and
+          <literal>ghcWithHoogle</literal> wrappers will now also
+          symlink GHC’s and all included libraries’ documentation to
+          <literal>$out/share/doc</literal> for convenience. If
+          undesired, the old behavior can be restored by overriding the
+          builders with
+          <literal>{ installDocumentation = false; }</literal>.
+        </para>
+      </listitem>
       <listitem>
         <para>
           <literal>mastodon</literal> now supports connection to a

nixos/doc/manual/release-notes/rl-2305.section.md

@@ -130,6 +130,11 @@ In addition to numerous new and upgraded packages, this release has the followin
 
 - The minimal ISO image now uses the `nixos/modules/profiles/minimal.nix` profile.
 
+- The `ghcWithPackages` and `ghcWithHoogle` wrappers will now also symlink GHC's
+  and all included libraries' documentation to `$out/share/doc` for convenience.
+  If undesired, the old behavior can be restored by overriding the builders with
+  `{ installDocumentation = false; }`.
+
 - `mastodon` now supports connection to a remote `PostgreSQL` database.
 
 - `services.peertube` now requires you to specify the secret file `secrets.secretsFile`. It can be generated by running `openssl rand -hex 32`.

pkgs/development/haskell-modules/with-packages-wrapper.nix

@@ -4,6 +4,8 @@
 # platform that has NCG support
 , useLLVM ? false
 , withHoogle ? false
+# Whether to install `doc` outputs for GHC and all included libraries.
+, installDocumentation ? true
 , hoogleWithPackages
 , postBuild ? ""
 , ghcLibdir ? null # only used by ghcjs, when resolving plugins
@@ -54,7 +56,11 @@ let
                   else "$out/lib/${ghc.targetPrefix}${ghc.haskellCompilerName}";
   docDir        = "$out/share/doc/ghc/html";
   packageCfgDir = "${libDir}/package.conf.d";
-  paths         = lib.filter (x: x ? isHaskellLibrary) (lib.closePropagation packages);
+  paths         = lib.concatLists (
+                    builtins.map
+                      (pkg: [ pkg ] ++ lib.optionals installDocumentation [ (lib.getOutput "doc" pkg) ])
+                      (lib.filter (x: x ? isHaskellLibrary) (lib.closePropagation packages))
+                  );
   hasLibraries  = lib.any (x: x.isHaskellLibrary) paths;
   # CLang is needed on Darwin for -fllvm to work:
   # https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/codegens.html#llvm-code-generator-fllvm
@@ -71,7 +77,9 @@ symlinkJoin {
   # if such a feature is needed, the real compiler name should be saved
   # as a dedicated drv attribute, like `compiler-name`
   name = ghc.name + "-with-packages";
-  paths = paths ++ [ghc];
+  paths = paths
+          ++ [ ghc ]
+          ++ lib.optionals installDocumentation [ ghc.doc ];
   nativeBuildInputs = [ makeWrapper ];
   postBuild = ''
     # wrap compiler executables with correct env variables