manual: add module

This module is capable of producing a bastardized NixOS configuration
manual with Home Manager configuration options instead.

modules/default.nix

@@ -7,6 +7,7 @@ let
 
   modules = [
     ./home-environment.nix
+    ./manual.nix
     ./programs/bash.nix
     ./programs/beets.nix
     ./programs/eclipse.nix
@@ -29,10 +30,12 @@ let
     ./systemd.nix
     ./xresources.nix
     ./xsession.nix
+    <nixpkgs/nixos/modules/misc/meta.nix>
   ];
 
   pkgsModule = {
     config._module.args.pkgs = lib.mkForce pkgs;
+    config._module.args.baseModules = modules;
   };
 
   module = lib.evalModules {

modules/manual.nix

@@ -0,0 +1,68 @@
+{ config, lib, pkgs, baseModules, ... }:
+
+with lib;
+
+let
+
+  /* For the purpose of generating docs, evaluate options with each derivation
+    in `pkgs` (recursively) replaced by a fake with path "\${pkgs.attribute.path}".
+    It isn't perfect, but it seems to cover a vast majority of use cases.
+    Caveat: even if the package is reached by a different means,
+    the path above will be shown and not e.g. `${config.services.foo.package}`. */
+  nixosManual = import <nixpkgs/nixos/doc/manual> {
+    inherit pkgs config;
+    version = "0.1";
+    revision = "release-0.1";
+    options =
+      let
+        scrubbedEval = evalModules {
+          modules = [ { nixpkgs.system = pkgs.stdenv.system; } ] ++ baseModules;
+          args = (config._module.args) // { modules = [ ]; };
+          specialArgs = { pkgs = scrubDerivations "pkgs" pkgs; };
+        };
+        scrubDerivations = namePrefix: pkgSet: mapAttrs
+          (name: value:
+            let wholeName = "${namePrefix}.${name}"; in
+            if isAttrs value then
+              scrubDerivations wholeName value
+              // (optionalAttrs (isDerivation value) { outPath = "\${${wholeName}}"; })
+            else value
+          )
+          pkgSet;
+      in scrubbedEval.options;
+  };
+
+  homeEnvironmentManPages = pkgs.runCommand "home-environment-manpages" {
+      allowedReferences = [ "out" ];
+    } ''
+      install -v -D -m444 \
+        ${nixosManual.manpages}/share/man/man5/configuration.nix.5 \
+        $out/share/man/man5/home-configuration.nix.5
+    '';
+
+in
+
+{
+  options = {
+    manual.manpages.enable = mkOption {
+      type = types.bool;
+      default = true;
+      example = false;
+      description = ''
+        Whether to install the configuration manual page. The manual can
+        be reached by <command>man home-configuration.nix</command>.
+        </para><para>
+        When looking at the manual page pretend that all references to
+        NixOS stuff are actually references to Home Manager stuff.
+        Thanks!
+      '';
+    };
+  };
+
+  config = mkIf config.manual.manpages.enable {
+    # To fix error during manpage build.
+    meta.doc = builtins.toFile "nothingness" "<para></para>";
+
+    home.packages = [ homeEnvironmentManPages ];
+  };
+}