From 597acd72f57ed398bf4219c57a249a664d6afecd Mon Sep 17 00:00:00 2001 From: fricklerhandwerk Date: Wed, 18 Oct 2023 12:04:34 +0200 Subject: [PATCH] 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 --- flake.lock | 84 +++++++++++++++++++++++++++++++++++---- flake.nix | 7 +++- source/conf.py | 5 +++ source/reference/index.md | 2 +- 4 files changed, 88 insertions(+), 10 deletions(-) diff --git a/flake.lock b/flake.lock index 1a027fd12..965e804bc 100644 --- a/flake.lock +++ b/flake.lock @@ -5,11 +5,11 @@ "systems": "systems" }, "locked": { - "lastModified": 1685518550, - "narHash": "sha256-o2d0KcvaXzTrPRIo0kOLV0/QXHhDQ5DTi+OxcjO8xqY=", + "lastModified": 1694529238, + "narHash": "sha256-zsNZZGTGnMOf9YpHKJqMSsa0dXbfmxeoJ7xHlrt+xmY=", "owner": "numtide", "repo": "flake-utils", - "rev": "a1720a10a6cfe8234c0e93907ffe81be440f4cef", + "rev": "ff7b65b44d01cf9ba6a71320833626af21126384", "type": "github" }, "original": { @@ -18,13 +18,82 @@ "type": "github" } }, + "lowdown-src": { + "flake": false, + "locked": { + "lastModified": 1633514407, + "narHash": "sha256-Dw32tiMjdK9t3ETl5fzGrutQTzh2rufgZV4A/BbxuD4=", + "owner": "kristapsdz", + "repo": "lowdown", + "rev": "d2c2b44ff6c27b936ec27358a2653caaef8f73b8", + "type": "github" + }, + "original": { + "owner": "kristapsdz", + "repo": "lowdown", + "type": "github" + } + }, + "nix_2-13": { + "inputs": { + "lowdown-src": "lowdown-src", + "nixpkgs": "nixpkgs", + "nixpkgs-regression": "nixpkgs-regression" + }, + "locked": { + "lastModified": 1691437145, + "narHash": "sha256-OCgwkDXvnMqfEsY5MIkrOzpF12iuSPS7l4hqY++W8a0=", + "owner": "NixOS", + "repo": "nix", + "rev": "38f4fe04e385693173cc41d7baf4228cf66d27e8", + "type": "github" + }, + "original": { + "owner": "NixOS", + "ref": "2.13-maintenance", + "repo": "nix", + "type": "github" + } + }, "nixpkgs": { "locked": { - "lastModified": 1685533922, - "narHash": "sha256-y4FCQpYafMQ42l1V+NUrMel9RtFtZo59PzdzflKR/lo=", + "lastModified": 1670461440, + "narHash": "sha256-jy1LB8HOMKGJEGXgzFRLDU1CBGL0/LlkolgnqIsF0D8=", + "owner": "NixOS", + "repo": "nixpkgs", + "rev": "04a75b2eecc0acf6239acf9dd04485ff8d14f425", + "type": "github" + }, + "original": { + "owner": "NixOS", + "ref": "nixos-22.11-small", + "repo": "nixpkgs", + "type": "github" + } + }, + "nixpkgs-regression": { + "locked": { + "lastModified": 1643052045, + "narHash": "sha256-uGJ0VXIhWKGXxkeNnq4TvV3CIOkUJ3PAoLZ3HMzNVMw=", + "owner": "NixOS", + "repo": "nixpkgs", + "rev": "215d4d0fd80ca5163643b03a33fde804a29cc1e2", + "type": "github" + }, + "original": { + "owner": "NixOS", + "repo": "nixpkgs", + "rev": "215d4d0fd80ca5163643b03a33fde804a29cc1e2", + "type": "github" + } + }, + "nixpkgs_2": { + "locked": { + "lastModified": 1697226376, + "narHash": "sha256-cumLLb1QOUtWieUnLGqo+ylNt3+fU8Lcv5Zl+tYbRUE=", "owner": "NixOS", "repo": "nixpkgs", - "rev": "3a70dd92993182f8e514700ccf5b1ae9fc8a3b8d", + "rev": "898cb2064b6e98b8c5499f37e81adbdf2925f7c5", "type": "github" }, "original": { @@ -37,7 +106,8 @@ "root": { "inputs": { "flake-utils": "flake-utils", - "nixpkgs": "nixpkgs" + "nix_2-13": "nix_2-13", + "nixpkgs": "nixpkgs_2" } }, "systems": { diff --git a/flake.nix b/flake.nix index 2ed694fad..2035d9067 100644 --- a/flake.nix +++ b/flake.nix @@ -3,8 +3,9 @@ inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.05"; inputs.flake-utils.url = "github:numtide/flake-utils"; + inputs.nix_2-13.url = "github:NixOS/nix/2.13-maintenance"; - outputs = { self, nixpkgs, flake-utils}: + outputs = { self, nixpkgs, flake-utils, nix_2-13 }: flake-utils.lib.eachDefaultSystem (system: let pkgs = import nixpkgs { @@ -15,6 +16,7 @@ (import ./overlay.nix) ]; }; + nix_2-13-doc = nix_2-13.packages.${system}.nix.doc; in { packages.default = pkgs.stdenv.mkDerivation { name = "nix-dev"; @@ -33,7 +35,8 @@ make html ''; installPhase = '' - mkdir -p $out + mkdir -p $out/manual/nix/2.13 + cp -R ${nix_2-13-doc}/share/doc/nix/manual/* $out/manual/nix/2.13 cp -R build/html/* $out/ ''; }; diff --git a/source/conf.py b/source/conf.py index 76c0aaff4..14b84bb5e 100644 --- a/source/conf.py +++ b/source/conf.py @@ -423,6 +423,11 @@ # 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 diff --git a/source/reference/index.md b/source/reference/index.md index 00dffe4ec..921171a22 100644 --- a/source/reference/index.md +++ b/source/reference/index.md @@ -7,7 +7,7 @@ These sections contains collections of detailed technical descriptions. :glob: :maxdepth: 2 -Nix Reference Manual +Nix Reference Manual Nixpkgs Manual NixOS Manual Recommended support tools