From e52438b8c665fe76267d8c93aeec4287aa873807 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Wed, 6 Dec 2023 03:31:01 +0100 Subject: [PATCH] generate index page from structured data - refactor `default.nix` for hopefully better readability - de-noise the overview page text --- default.nix | 124 +++++++++++++++++++-------------- source/reference/nix-manual.md | 32 +++++---- 2 files changed, 92 insertions(+), 64 deletions(-) diff --git a/default.nix b/default.nix index 1cb0ec9..2cc6937 100644 --- a/default.nix +++ b/default.nix @@ -9,59 +9,81 @@ let inherit system; }; - nix-dev = pkgs.stdenv.mkDerivation { - name = "nix-dev"; - src = ./.; - nativeBuildInputs = with pkgs.python310.pkgs; [ - linkify-it-py - myst-parser - sphinx - sphinx-book-theme - sphinx-copybutton - sphinx-design - sphinx-notfound-page - sphinx-sitemap - ]; - buildPhase = '' - make html - ''; - installPhase = - let - # Various versions of the Nix manuals, grep for (nix-manual)= to find where they are displayed - # FIXME: This requires human interaction to update! See ./CONTRIBUTING.md for details. - releases = { - latest = "2.19"; - rolling = "2.18"; - stable = "2.18"; - prev-stable = "2.13"; - }; - inputName = version: pkgs.lib.strings.replaceStrings [ "." ] [ "-" ] version; - src = version: inputs."nix_${inputName version}"; - manual = version: (import (src version)).default.doc; - copy = version: '' - cp -Rf ${manual version}/share/doc/nix/manual/* $out/manual/nix/${version} + nix-dev = + let + # Various versions of the Nix manuals, grep for (nix-manual)= to find where they are displayed + # FIXME: This requires human interaction to update! See ./CONTRIBUTING.md for details. + nix-releases = { + latest = "2.19"; + rolling = "2.18"; + stable = "2.18"; + prev-stable = "2.13"; + }; + nixpkgs-releases = { + stable = "23.11"; + prev-stable = "23.05"; + }; + in + pkgs.stdenv.mkDerivation { + name = "nix-dev"; + src = ./.; + nativeBuildInputs = with pkgs.python310.pkgs; [ + linkify-it-py + myst-parser + sphinx + sphinx-book-theme + sphinx-copybutton + sphinx-design + sphinx-notfound-page + sphinx-sitemap + ]; + buildPhase = + let + nix-manual-index = + with pkgs.lib.attrsets; + let + raw = builtins.readFile ./source/reference/nix-manual.md; + nix-replacements = mapAttrsToList (release: version: "@${release}@") nix-releases; + nixpkgs-replacements = mapAttrsToList (release: version: "@nixpkgs-${release}@") nixpkgs-releases; + in + pkgs.lib.strings.replaceStrings + (nix-replacements ++ nixpkgs-replacements) + (attrValues nix-releases ++ attrValues nixpkgs-releases) + raw; + in + '' + cp -f ${builtins.toFile "nix-manual.md" nix-manual-index} $TMP/nix.dev/source/reference/nix-manual.md + make html ''; - # add upstream page redirects of the form ` `, excluding comment lines and empty - redirects = version: '' - sed '/^#/d;/^$/d;s#^\(.*\) \(.*\) #/manual/nix/${version}\1 /manual/nix/${version}\2 #g' ${src version}/doc/manual/_redirects >> $out/_redirects + installPhase = + with pkgs.lib.attrsets; + with pkgs.lib.strings; + let + nix-versions = with pkgs.lib; lists.unique (attrsets.attrValues nix-releases); + inputName = version: pkgs.lib.strings.replaceStrings [ "." ] [ "-" ] version; + nix-src = version: inputs."nix_${inputName version}"; + nix-manual = version: (import (nix-src version)).default.doc; + copy = version: '' + cp -Rf ${nix-manual version}/share/doc/nix/manual/* $out/manual/nix/${version} + ''; + # add upstream page redirects of the form ` `, excluding comment lines and empty + redirects = version: '' + sed '/^#/d;/^$/d;s#^\(.*\) \(.*\) #/manual/nix/${version}\1 /manual/nix/${version}\2 #g' ${nix-src version}/doc/manual/_redirects >> $out/_redirects + ''; + shortlink = release: version: '' + echo /manual/nix/${release} /manual/nix/${version}/ 302 >> $out/_redirects + ''; + in + '' + mkdir -p $out + cp -R build/html/* $out/ + # NOTE: the comma in the shell expansion makes it also work for singleton lists + mkdir -p $out/manual/nix/{${concatStringsSep "," nix-versions},} + ${concatStringsSep "\n" (map copy nix-versions)} + ${concatStringsSep "\n" (map redirects nix-versions)} + ${concatStringsSep "\n" (mapAttrsToList shortlink nix-releases)} ''; - shortlink = release: version: '' - echo /manual/nix/${release} /manual/nix/${version}/ 302 >> $out/_redirects - ''; - versions = with pkgs.lib; lists.unique (attrsets.attrValues releases); - in - with pkgs.lib.attrsets; - with pkgs.lib.strings; - '' - mkdir -p $out - cp -R build/html/* $out/ - # NOTE: the comma in the shell expansion makes it also work for singleton lists - mkdir -p $out/manual/nix/{${concatStringsSep "," versions},} - ${concatStringsSep "\n" (map copy versions)} - ${concatStringsSep "\n" (map redirects versions)} - ${concatStringsSep "\n" (mapAttrsToList shortlink releases)} - ''; - }; + }; devmode = let diff --git a/source/reference/nix-manual.md b/source/reference/nix-manual.md index 7e67a08..367c687 100644 --- a/source/reference/nix-manual.md +++ b/source/reference/nix-manual.md @@ -1,35 +1,41 @@ (nix-manual)= # Nix reference manual + + ```{toctree} :hidden: Nix pre-release (development) -Nix 2.19 (latest) -Nix 2.18 (rolling) -Nix 2.18 (stable 23.11) -Nix 2.13 (stable 23.05) +Nix @latest@ (latest) +Nix @rolling@ (in rolling) +Nix @stable@ (in stable @nixpkgs-stable@) +Nix @prev-stable@ (in stable @nixpkgs-prev-stable@) ``` - [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) + 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/) +- [Nix @latest@](https://nix.dev/manual/nix/latest/) - Reference documentation for the latest Nix release + Latest Nix release -- [Nix 2.18](https://nix.dev/manual/nix/2.18/) +- [Nix @rolling@](https://nix.dev/manual/nix/rolling/) - Reference documentation for the Nix version shipped with the {term}`Nixpkgs` and {term}`NixOS` rolling release + Shipped with the {term}`Nixpkgs` and {term}`NixOS` rolling release -- [Nix 2.18](https://nix.dev/manual/nix/2.18/) +- [Nix @stable@](https://nix.dev/manual/nix/stable/) - Reference documentation for the Nix version shipped with the current {term}`Nixpkgs` and {term}`NixOS` stable release + Shipped with the current {term}`Nixpkgs` and {term}`NixOS` @nixpkgs-stable@ stable release -- [Nix 2.13](https://nix.dev/manual/nix/2.13/) +- [Nix @prev-stable@](https://nix.dev/manual/nix/prev-stable/) - Reference documentation for the Nix version shipped with the previous {term}`Nixpkgs` and {term}`NixOS` stable release + Shipped with the previous {term}`Nixpkgs` and {term}`NixOS` @nixpkgs-prev-stable@ stable release :::{tip} More information on Nixpkgs and NixOS releases: [](channel-branches)