host Nix reference manual on nix.dev

this is the most cursed setup you will see any time soon.

we're dumping the Nix manual unchanged into the build tree *after*
building. the reason is that we'd want to link to it from our table of
contents, but because Sphinx does not allow adding arbitrary files to
the build output in arbitrary locations (only `_static` works). but we
want to place the manual behind a particular URL, and the alternative of
maintaining URL rewrites (e.g. in nginx) is not accessible here because the
infrastructure is managed somewhere else.

now that the files won't appear in their desired locations at Sphinx
build time, we can't use relative links to reference them, therefore we
have to resort to pointing to the web URL the manual will appear at.
this is terrible and I'm sorry. please fix this if you have a better
idea. once we use URLs though, we have to avoid linkchecking, since
those files may not be there before deploying them.

figuring all of this out took way longer than anyone would wish.

Co-authored-by: Alejandro Sanchez Medina <alejandrosanchzmedina@gmail.com>

default.nix

@@ -25,8 +25,26 @@ let
     buildPhase = ''
       make html
     '';
-    installPhase = ''
-      mkdir -p $out
+    installPhase =
+      let
+        # Various versions of the Nix manuals, grep for (nix-manual)=
+        # FIXME: This requires human interaction to update!
+        # See ./CONTRIBUTING.md for details.
+        releases = [
+          "2.19"
+          "2.18"
+          "2.13"
+        ];
+        inputName = version: pkgs.lib.strings.replaceStrings [ "." ] [ "-" ] version;
+        src = version: (import inputs."nix_${inputName version}").default.doc;
+        copy = version: ''
+          cp -R ${src version}/share/doc/nix/manual/* $out/manual/nix/${version}
+        '';
+      in
+      with pkgs.lib.strings;
+      ''
+        mkdir -p $out/manual/nix/{${concatStringsSep "," releases}}
+        ${concatStringsSep "\n" (map copy releases)}
         cp -R build/html/* $out/
       '';
   };
@@ -68,6 +86,7 @@ in
     inputsFrom = [ nix-dev ];
     packages = [
       devmode
+      pkgs.niv
       pkgs.python310.pkgs.black
       pkgs.vale
     ];

nix/sources.json

@@ -1,4 +1,40 @@
 {
+    "nix_2-13": {
+        "branch": "2.13-maintenance",
+        "description": "Nix, the purely functional package manager",
+        "homepage": "https://nixos.org/",
+        "owner": "nixos",
+        "repo": "nix",
+        "rev": "56eb17906822f14bb348017315cb1ca643da900a",
+        "sha256": "1k0x63l9crkrhdgdclcx8mp6r9mcp4brs67l6hsii1ag8gy2gmj4",
+        "type": "tarball",
+        "url": "https://github.com/nixos/nix/archive/56eb17906822f14bb348017315cb1ca643da900a.tar.gz",
+        "url_template": "https://github.com/<owner>/<repo>/archive/<rev>.tar.gz"
+    },
+    "nix_2-18": {
+        "branch": "2.18-maintenance",
+        "description": "Nix, the purely functional package manager",
+        "homepage": "https://nixos.org/",
+        "owner": "nixos",
+        "repo": "nix",
+        "rev": "f5f4de6a550327b4b1a06123c2e450f1b92c73b6",
+        "sha256": "1g23sxsh9aj7sard5d3ijqfjqbh4fvlvyr73sj3dcdzcqiys5naq",
+        "type": "tarball",
+        "url": "https://github.com/nixos/nix/archive/f5f4de6a550327b4b1a06123c2e450f1b92c73b6.tar.gz",
+        "url_template": "https://github.com/<owner>/<repo>/archive/<rev>.tar.gz"
+    },
+    "nix_2-19": {
+        "branch": "2.19-maintenance",
+        "description": "Nix, the purely functional package manager",
+        "homepage": "https://nixos.org/",
+        "owner": "nixos",
+        "repo": "nix",
+        "rev": "33bacbe220b49ceaaeb817354592a0102fbae087",
+        "sha256": "17fjz3mxqcszxfzpj48f8rqzdqavnnpibpi0ssw7vxmyybrqsqly",
+        "type": "tarball",
+        "url": "https://github.com/nixos/nix/archive/33bacbe220b49ceaaeb817354592a0102fbae087.tar.gz",
+        "url_template": "https://github.com/<owner>/<repo>/archive/<rev>.tar.gz"
+    },
     "nixpkgs": {
         "branch": "nixos-23.05",
         "description": "Nix Packages collection & NixOS",

source/conf.py

@@ -423,6 +423,11 @@ linkcheck_ignore = [
     # Linkcheck fails on anchors in GH browser/file viewer, see https://github.com/sphinx-doc/sphinx/issues/11484
     r"https://github\.com/.+/.+/blob/.*#.*$",
     r"https://github\.com/.+/.+/tree/.*#.*$",
+    # XXX: we use the web URL to the manuals we host within the build output,
+    # because Sphinx does not have facilities to deploy arbitrary files.
+    # since linkchecking those URLs will fail before actually deploying them,
+    # we ignore them here.
+    r"https://nix.dev/manual/.*$",
 ]
 
 # Anchors are not present in HTML

source/reference/glossary.md

@@ -7,7 +7,7 @@ Nix
     Read /nɪks/ ("Niks").
 
     :::{seealso}
-    - [Nix Reference Manual](https://nixos.org/manual/nix)
+    - [Nix Reference Manual](./nix-manual.md)
     - [Nix source code](https://github.com/NixOS/nix)
     :::
 

source/reference/index.md

@@ -7,7 +7,7 @@ These sections contains collections of detailed technical descriptions.
 :glob:
 :maxdepth: 2
 
-Nix Reference Manual <https://nixos.org/manual/nix/stable/>
+./nix-manual.md
 Nixpkgs Manual <https://nixos.org/manual/nixpkgs/stable/>
 NixOS Manual <https://nixos.org/manual/nixos/stable/>
 Recommended support tools <https://github.com/nix-community/awesome-nix>

source/reference/nix-manual.md

@@ -0,0 +1,27 @@
+(nix-manual)=
+# Nix reference manual
+
+```{toctree}
+:hidden:
+
+Nix pre-release (development) <https://hydra.nixos.org/job/nix/master/build.x86_64-linux/latest/download>
+Nix 2.19 (latest) <https://nix.dev/manual/nix/2.19/>
+Nix 2.18 (rolling) <https://nix.dev/manual/nix/2.18/>
+Nix 2.13 (stable) <https://nix.dev/manual/nix/2.17/>
+```
+
+- [Nix pre-release](https://hydra.nixos.org/job/nix/master/build.x86_64-linux/latest/download)
+
+  Reference documentation for the latest build from the `master` branch of the [Nix repository](https://github.com/NixOS/nix)
+
+- [Nix 2.19](https://nix.dev/manual/nix/2.19/)
+
+  Reference documentation for the latest Nix release
+
+- [Nix 2.18](https://nix.dev/manual/nix/2.18/)
+
+  Reference documentation for the Nix version shipped with the {term}`Nixpkgs` and {term}`NixOS` rolling release
+
+- [Nix 2.13 ](https://nix.dev/manual/nix/2.13/)
+
+  Reference documentation for the Nix version shipped with the current {term}`Nixpkgs` and {term}`NixOS` stable release