flake: rename packages.«system».docs to packages.«system».doc (#1407)

Rename packages.«system».docs to packages.«system».doc, following the
discussion in [1] ("doc: move to doc directory").

[1]: https://github.com/nix-community/stylix/pull/1272#discussion_r2097630348

Link: https://github.com/nix-community/stylix/pull/1407

Reviewed-by: awwpotato <awwpotato@voidq.com>
Reviewed-by: NAHO <90870942+trueNAHO@users.noreply.github.com>

doc/server.nix

@@ -1,5 +1,5 @@
 {
-  docs,
+  doc,
   http-server,
   writeShellApplication,
 }:
@@ -17,6 +17,6 @@ writeShellApplication {
     "-o"
   ];
   text = ''
-    http-server ${docs} "''${server_flags[@]}"
+    http-server ${doc} "''${server_flags[@]}"
   '';
 }

flake/default.nix

@@ -1,6 +1,6 @@
 {
   imports = [
-    ./deprecated.nix
+    ./deprecation
     ./dev-shell.nix
     ./modules.nix
     ./packages.nix

flake/deprecation/default.nix

@@ -4,6 +4,10 @@
   ...
 }:
 {
+  imports = [
+    ./per-system-option.nix
+  ];
+
   # NOTE: the `flake` submodule has a `lazyAttrsOf` freeform type.
   #
   # This means a `mkIf false` definition will not omit the attr, because
@@ -14,6 +18,21 @@
 
   # Drop this alias after 26.05
   flake = lib.mkIf (!lib.oldestSupportedReleaseIsAtLeast 2605) {
-    homeManagerModules = builtins.warn "stylix: flake output `homeManagerModules` has been renamed to `homeModules`" self.homeModules;
+    homeManagerModules = builtins.warn "stylix: flake output `homeManagerModules` has been renamed to `homeModules` and will be removed after 26.05." self.homeModules;
   };
+
+  perSystem.stylix.aliases = [
+    {
+      output = "apps";
+      old = "docs";
+      new = "doc";
+      until = 2511;
+    }
+    {
+      output = "packages";
+      old = "docs";
+      new = "doc";
+      until = 2511;
+    }
+  ];
 }

flake/deprecation/per-system-option.nix

@@ -0,0 +1,86 @@
+{ lib, config, ... }:
+{
+  perSystem.options.stylix.aliases = lib.mkOption {
+    type = lib.types.listOf (
+      lib.types.submodule {
+        options = {
+          output = lib.mkOption {
+            type = lib.types.str;
+            description = ''
+              The per-system attribute in which to define the alias.
+            '';
+          };
+          old = lib.mkOption {
+            type = lib.types.str;
+            description = "The name of the alias.";
+          };
+          new = lib.mkOption {
+            type = lib.types.str;
+            description = "The name of the alias target.";
+          };
+          since = lib.mkOption {
+            type = with lib.types; nullOr ints.unsigned;
+            default = null;
+            description = ''
+              Warn only once the specified release is the oldest supported
+              nixpkgs release.
+
+              If `null`, the alias will always warn.
+            '';
+          };
+          until = lib.mkOption {
+            type = lib.types.ints.unsigned;
+            description = ''
+              Create the alias only until the specified release is the oldest
+              supported nixpkgs release.
+
+              The alias spec can be safely removed after this release.
+            '';
+          };
+        };
+      }
+    );
+    default = [ ];
+    description = "A list of per-system aliases.";
+  };
+
+  # Transpose per-system aliases to the top-level
+  flake = lib.mkMerge (
+    lib.mapAttrsToList (
+      system: cfg:
+      let
+        # Produces config definition for an alias
+        mkAlias =
+          {
+            output,
+            since,
+            until,
+            old,
+            new,
+          }:
+          let
+            paths = builtins.mapAttrs (_: attr: [
+              output
+              system
+              attr
+            ]) { inherit old new; };
+            names = builtins.mapAttrs (_: lib.showAttrPath) paths // {
+              until = lib.pipe until [
+                builtins.toString
+                (builtins.match "([[:digit:]]{2})([[:digit:]]{2})")
+                (lib.concatStringsSep ".")
+              ];
+            };
+          in
+          lib.mkIf (!lib.oldestSupportedReleaseIsAtLeast until) (
+            lib.attrsets.setAttrByPath paths.old (
+              lib.warnIf (since != null -> lib.oldestSupportedReleaseIsAtLeast since)
+                "stylix: flake output `${names.old}` has been renamed to `${names.new}` and will be removed after ${names.until}."
+                (cfg.${output}.${new} or (throw "stylix: flake alias not found: ${names.new}"))
+            )
+          );
+      in
+      lib.mkMerge (map mkAlias cfg.stylix.aliases)
+    ) config.allSystems
+  );
+}

flake/dev-shell.nix

@@ -35,7 +35,7 @@
       # not the local flake worktree that has possibly been modified since
       # entering the devshell.
       build-and-run-docs = pkgs.writeShellScriptBin "serve-docs" ''
-        nix run .#docs
+        nix run .#doc
       '';
     in
     {

flake/packages.nix

@@ -9,7 +9,7 @@
       checks = config.packages;
 
       # Make 'nix run .#docs' serve the docs
-      apps.docs.program = config.packages.serve-docs;
+      apps.doc.program = config.packages.serve-docs;
 
       packages = lib.mkMerge [
         # Testbeds are virtual machines based on NixOS, therefore they are
@@ -20,13 +20,13 @@
           }
         ))
         {
-          docs = pkgs.callPackage ../doc {
+          doc = pkgs.callPackage ../doc {
             inherit inputs;
             inherit (inputs.nixpkgs.lib) nixosSystem;
             inherit (inputs.home-manager.lib) homeManagerConfiguration;
           };
           serve-docs = pkgs.callPackage ../doc/server.nix {
-            inherit (config.packages) docs;
+            inherit (config.packages) doc;
           };
           palette-generator = pkgs.callPackage ../palette-generator { };
         }