doc: split modules into separate pages (#873)

docs/book.toml

@@ -2,7 +2,17 @@
 title = "Stylix"
 language = "en"
 
+[preprocessor.alerts]
+
 [output.html]
 git-repository-url = "https://github.com/danth/stylix"
 edit-url-template = "https://github.com/danth/stylix/edit/master/docs/{path}"
+no-section-label = true
 
+[output.html.fold]
+enable = true
+
+[output.html.redirect]
+# Must use relative paths with . or .. for offline browsing to work correctly
+"/options/hm.html" = "./platforms/home_manager.html"
+"/options/nixos.html" = "./platforms/nixos.html"

docs/default.nix

@@ -6,73 +6,179 @@
 }:
 
 let
-  makeOptionsDoc =
-    configuration:
-    pkgs.nixosOptionsDoc {
-      inherit (configuration) options;
+  nixosConfiguration = lib.nixosSystem {
+    inherit (pkgs) system;
+    modules = [
+      inputs.home-manager.nixosModules.home-manager
+      inputs.self.nixosModules.stylix
+      ./settings.nix
+    ];
+  };
 
-      # Filter out any options not beginning with `stylix`
+  homeManagerConfiguration = inputs.home-manager.lib.homeManagerConfiguration {
+    inherit pkgs;
+    modules = [
+      inputs.self.homeManagerModules.stylix
+      ./settings.nix
+      {
+        home = {
+          homeDirectory = "/home/book";
+          stateVersion = "22.11";
+          username = "book";
+        };
+      }
+    ];
+  };
+
+  # TODO: Include Nix Darwin options
+
+  makeOptionsDoc =
+    { configuration, pathFilter }:
+    (pkgs.nixosOptionsDoc {
+      inherit (configuration) options;
       transformOptions =
+        let
+          commit = inputs.self.rev or "master";
+          declarationPrefix = toString inputs.self;
+        in
         option:
         option
         // {
-          visible = option.visible && builtins.elemAt option.loc 0 == "stylix";
+          declarations = map (
+            declaration:
+            let
+              declarationString = toString declaration;
+              declarationWithoutprefix = lib.removePrefix "${declarationPrefix}/" declarationString;
+            in
+            lib.throwIfNot (lib.hasPrefix declarationPrefix declarationString)
+              "declaration not in ${declarationPrefix}: ${declarationString}"
+              {
+                name = "<${declarationWithoutprefix}>";
+                url = "https://github.com/danth/stylix/blob/${commit}/${declarationWithoutprefix}";
+              }
+          ) option.declarations;
+
+          visible = option.visible && lib.any pathFilter option.declarations;
         };
+    }).optionsCommonMark;
+
+  # The documentation for options which aren't linked to a specific module
+  makePlatformsOptionsDoc =
+    configuration:
+    makeOptionsDoc {
+      inherit configuration;
+      pathFilter =
+        path:
+        lib.hasPrefix "${inputs.self}/" path
+        && !lib.hasPrefix "${inputs.self}/modules/" path;
     };
 
-  nixos = makeOptionsDoc (
-    lib.nixosSystem {
-      inherit (pkgs) system;
-      modules = [
-        inputs.home-manager.nixosModules.home-manager
-        inputs.self.nixosModules.stylix
-        ./settings.nix
-      ];
-    }
-  );
+  # Returns an attribute set of module names and their corresponding option
+  # documentation.
+  makeModuleOptionsDoc =
+    configuration:
+    lib.mapAttrs (
+      module: _:
+      makeOptionsDoc {
+        inherit configuration;
+        pathFilter = lib.hasPrefix "${inputs.self}/modules/${module}/";
+      }
+    ) (builtins.readDir "${inputs.self}/modules");
 
-  homeManager = makeOptionsDoc (
-    inputs.home-manager.lib.homeManagerConfiguration {
-      inherit pkgs;
-      modules = [
-        inputs.self.homeManagerModules.stylix
-        ./settings.nix
-        {
-          home = {
-            homeDirectory = "/home/book";
-            stateVersion = "22.11";
-            username = "book";
-          };
-        }
-      ];
-    }
-  );
+  nixosModuleOptionsDoc = makeModuleOptionsDoc nixosConfiguration;
+  homeManagerModuleOptionsDoc = makeModuleOptionsDoc homeManagerConfiguration;
+
+  modulePageScript = lib.pipe "${inputs.self}/modules" [
+    builtins.readDir
+    (lib.mapAttrsToList (
+      module: _: ''
+        writeModulePage \
+          ${module} \
+          ${homeManagerModuleOptionsDoc.${module}} \
+          ${nixosModuleOptionsDoc.${module}}
+      ''
+    ))
+    lib.concatStrings
+  ];
 
 in
 pkgs.stdenvNoCC.mkDerivation {
   name = "stylix-book";
   src = ./.;
+  buildInputs = with pkgs; [
+    mdbook
+    mdbook-alerts
+  ];
 
   patchPhase = ''
+    # The generated documentation has headings at level 2, but we want level 3
+    # so they can be nested under the sections for each module system.
+    REDUCE_HEADINGS='s/^## /### /'
+
+    function writeOptions() {
+      platformName="$1"
+      optionsFile="$2"
+      outputFile="$3"
+
+      printf '\n## %s options\n' "$platformName" >>"$outputFile"
+
+      if [[ -s "$optionsFile" ]]; then
+        sed \
+          --expression "$REDUCE_HEADINGS" \
+          <"$optionsFile" \
+          >>"$outputFile"
+      else
+        printf '*%s*\n' "None provided." >>"$outputFile"
+      fi
+    }
+
+    function writeModulePage() {
+      moduleName="$1"
+      homeManagerOptionsFile="$2"
+      nixosOptionsFile="$3"
+
+      readmeFile="${inputs.self}/modules/$moduleName/README.md"
+      page="options/modules/$moduleName.md"
+      outputFile="src/$page"
+
+      if [[ -f $outputFile ]]; then
+        printf \
+          '%s should not be used. Move it to %s\n' \
+          "docs/src/options/modules/$moduleName.md" \
+          "modules/$moduleName/README.md" \
+          >&2
+        exit 1
+
+      elif [[ -f $readmeFile ]]; then
+        cp --no-preserve=mode,ownership "$readmeFile" "$outputFile"
+
+      else
+        printf \
+          '%s\n' \
+          "# $moduleName" \
+          '> [!NOTE]' \
+          "> This module doesn't include any additional documentation." \
+          '> You can browse the options it provides below.' \
+          >>"$outputFile"
+      fi
+
+      writeOptions 'Home Manager' "$homeManagerOptionsFile" "$outputFile"
+      writeOptions 'NixOS' "$nixosOptionsFile" "$outputFile"
+
+      printf '  - [%s](%s)\n' "$moduleName" "$page" >>src/SUMMARY.md
+    }
+
     cp ${../README.md} src/README.md
     cp ${../gnome.png} src/gnome.png
     cp ${../kde.png} src/kde.png
 
-    # mdBook doesn't support this Markdown extension yet
-    substituteInPlace **/*.md \
-      --replace-quiet '> [!NOTE]' '> **Note**' \
-      --replace-quiet '> [!TIP]' '> **Tip**' \
-      --replace-quiet '> [!IMPORTANT]' '> **Important**' \
-      --replace-quiet '> [!WARNING]' '> **Warning**' \
-      --replace-quiet '> [!CAUTION]' '> **Caution**'
+    mkdir --parents src/options/platforms
+    writeOptions 'Home Manager' ${(makePlatformsOptionsDoc homeManagerConfiguration)} src/options/platforms/home_manager.md
+    writeOptions 'NixOS' ${(makePlatformsOptionsDoc nixosConfiguration)} src/options/platforms/nixos.md
 
-    # The "declared by" links point to a file which only exists when the docs
-    # are built locally. This removes the links.
-    sed '/*Declared by:*/,/^$/d' <${nixos.optionsCommonMark} >>src/options/nixos.md
-    sed '/*Declared by:*/,/^$/d' <${homeManager.optionsCommonMark} >>src/options/hm.md
+    mkdir --parents src/options/modules
+    ${modulePageScript}
   '';
 
-  buildPhase = ''
-    ${pkgs.mdbook}/bin/mdbook build --dest-dir $out
-  '';
+  buildPhase = "mdbook build --dest-dir $out";
 }

docs/src/SUMMARY.md

@@ -6,11 +6,6 @@
 - [Configuration](configuration.md)
 - [Tips and tricks](tricks.md)
 
-# Reference
-
-- [NixOS options](options/nixos.md)
-- [Home Manager options](options/hm.md)
-
 # Contributing
 
 - [Commit Convention](commit_convention.md)
@@ -18,3 +13,16 @@
 - [Adding modules](modules.md)
 - [Testbeds](testbeds.md)
 - [Style guide](styling.md)
+
+# Reference
+
+<!--
+  The auto-generated list of modules is appended to this file, so this must
+  be the last section, and modules must be the last page, with no comments
+  following it. There must be a trailing newline.
+-->
+
+- [Platforms]() <!-- TODO: migrate general platforms content to this page. -->
+  - [Home Manager](options/platforms/home_manager.md)
+  - [NixOS](options/platforms/nixos.md)
+- [Modules]() <!-- TODO: migrate general modules content to this page. -->

docs/src/configuration.md

@@ -182,37 +182,39 @@ theme for each user.
 
 You may prefer to disable inheritance entirely, and set up the Home Manager
 version of Stylix yourself if required. Refer to the options
-[`stylix.homeManagerIntegration.autoImport`](options/nixos.md#stylixhomemanagerintegrationautoimport)
+[`stylix.homeManagerIntegration.autoImport`](options/global/nixos.md#stylixhomemanagerintegrationautoimport)
 and
-[`stylix.homeManagerIntegration.followSystem`](options/nixos.md#stylixhomemanagerintegrationfollowsystem)
+[`stylix.homeManagerIntegration.followSystem`](options/global/nixos.md#stylixhomemanagerintegrationfollowsystem)
 to customize this.
 
 > [!NOTE]
 >
 > There is a special case involving the
-> [`stylix.base16Scheme`](options/nixos.md#stylixbase16scheme)
+> [`stylix.base16Scheme`](options/global/nixos.md#stylixbase16scheme)
 > option:
 >
 > If the wallpaper in a Home Manager configuration is changed, then Home Manager
 > will stop inheriting the color scheme from NixOS. This allows Home Manager
 > configurations to use the automatic palette generator without being overridden.
 >
-> Similarly, [`stylix.override`](options/nixos.md#stylixoverride) is not inherited
+> Similarly, [`stylix.override`](options/global/nixos.md#stylixoverride) is not inherited
 > if the color scheme is different.
 
 ## Turning targets on and off
 
-In Stylix terms, a target is anything which can have colors, fonts or a
-wallpaper applied to it. Each module in this repository should correspond to a
-target of the same name.
+A target is anything which can have colors, fonts or a wallpaper applied to it.
 
-Each target has an option like `stylix.targets.«target».enable` to turn its
-styling on or off. Normally, it's turned on automatically when the target is
-installed. You can set `stylix.autoEnable = false` to opt out of this
-behaviour, in which case you'll need to manually enable each target you want to
-be styled.
+You can discover the available targets and their options by browsing through
+the module reference at the end of this book. Most targets will be found under
+a module of the same name, but occasionally a module will serve multiple similar
+targets. For example, the [Firefox module](options/modules/firefox.md) also
+provides options for other browsers which are based on Firefox.
+
+For each target, there is an option like `stylix.targets.«target».enable` which
+you can use to turn its styling on or off. By default, it's turned on
+automatically whenever the target is installed. You can globally set
+`stylix.autoEnable = false` to opt out of this behaviour, in which case you'll
+need to manually enable each target you want to be themed.
 
 Targets are different between Home Manager and NixOS, and sometimes available
 in both cases. If both are available, it is always correct to enable both.
-The reference pages have a list of targets for [NixOS](options/nixos.md) and
-[Home Manager](options/hm.md) respectively.

docs/src/modules.md

@@ -71,11 +71,6 @@ one of the following applies:
 - There is no reliable way to detect whether the target is installed, *and*
   enabling it unconditionally would cause problems.
 
-## Testbeds
-
-Adding [testbeds](./testbeds.md) for new modules is encouraged, but not
-mandatory.
-
 ## How to apply colors
 
 Refer to the [style guide](./styling.md) to see how colors are named,
@@ -117,3 +112,29 @@ slow and should be avoided.
 
 For everything else, like fonts and wallpapers, you can just take option values
 directly from `config`. See the reference pages for a list of options.
+
+## Documentation
+
+Documentation for options is automatically generated. To improve the quality
+of this documentation, ensure that any custom options created using `mkOption`
+are given an appropriate `type` and a detailed `description`. This may use
+Markdown syntax for formatting and links.
+
+For modules needing more general documentation, create
+`modules/«module»/README.md`:
+
+```markdown
+# Module Name
+
+Consider describing which applications are themed by this module (if it's not
+obvious from the module name), how the applications need to be installed for the
+module to work correctly, which theming items are supported (colors, fonts,
+wallpaper, ...), and any caveats the user should be aware of.
+```
+
+This will be inserted before the automatically generated list of options.
+
+## Testbeds
+
+Adding [testbeds](./testbeds.md) for new modules is encouraged, but not
+mandatory.

docs/src/options/platforms/home_manager.md

@@ -1,4 +1,4 @@
-# Home Manager options
+# Home Manager
 
 The following options can only be set in a Home Manager configuration.
 
@@ -19,6 +19,6 @@ home-manager.users.«name» = {
 };
 ```
 
-[Read more about per-user themes.](../configuration.md#multi-user-configurations)
+[Read more about per-user themes.](../../configuration.md#multi-user-configurations)
 
 <!-- Auto-generated documentation will be added below. -->

docs/src/options/platforms/nixos.md

@@ -1,4 +1,4 @@
-# NixOS options
+# NixOS
 
 The following options can only be set in a NixOS configuration.
 

flake.nix

@@ -216,11 +216,14 @@
         { pkgs, ... }@args:
         {
           imports = [
-            (import ./stylix/nixos inputs {
-              inherit (self.packages.${pkgs.system}) palette-generator;
-              base16 = base16.lib args;
-              homeManagerModule = self.homeManagerModules.stylix;
-            })
+            (import ./stylix/nixos inputs)
+            {
+              stylix = {
+                paletteGenerator = self.packages.${pkgs.system}.palette-generator;
+                base16 = base16.lib args;
+                homeManagerIntegration.module = self.homeManagerModules.stylix;
+              };
+            }
           ];
         };
 
@@ -228,10 +231,13 @@
         { pkgs, ... }@args:
         {
           imports = [
-            (import ./stylix/hm inputs {
-              inherit (self.packages.${pkgs.system}) palette-generator;
-              base16 = base16.lib args;
-            })
+            (import ./stylix/hm inputs)
+            {
+              stylix = {
+                paletteGenerator = self.packages.${pkgs.system}.palette-generator;
+                base16 = base16.lib args;
+              };
+            }
           ];
         };
 
@@ -239,11 +245,14 @@
         { pkgs, ... }@args:
         {
           imports = [
-            (import ./stylix/darwin inputs {
-              inherit (self.packages.${pkgs.system}) palette-generator;
-              base16 = base16.lib args;
-              homeManagerModule = self.homeManagerModules.stylix;
-            })
+            (import ./stylix/darwin inputs)
+            {
+              stylix = {
+                paletteGenerator = self.packages.${pkgs.system}.palette-generator;
+                base16 = base16.lib args;
+                homeManagerIntegration.module = self.homeManagerModules.stylix;
+              };
+            }
           ];
         };
     };

stylix/darwin/default.nix

@@ -1,22 +1,23 @@
 inputs:
-{
-  palette-generator,
-  base16,
-  homeManagerModule,
-}:
 { lib, ... }:
 
+# Imported modules which define new options must use an absolute path based
+# on ${inputs.self}, otherwise those options will not appear in the generated
+# documentation.
+
 let
   autoload = import ../autoload.nix { inherit lib inputs; } "darwin";
 in
 {
   imports = [
-    ../pixel.nix
-    ../target.nix
-    ../opacity.nix
-    ./fonts.nix
-    (import ./palette.nix { inherit palette-generator base16; })
+    "${inputs.self}/stylix/darwin/fonts.nix"
+    "${inputs.self}/stylix/darwin/palette.nix"
+    "${inputs.self}/stylix/fonts.nix"
+    "${inputs.self}/stylix/home-manager-integration.nix"
+    "${inputs.self}/stylix/opacity.nix"
+    "${inputs.self}/stylix/palette.nix"
+    "${inputs.self}/stylix/pixel.nix"
+    "${inputs.self}/stylix/target.nix"
     (import ../templates.nix inputs)
-    (import ../home-manager-integration.nix homeManagerModule)
   ] ++ autoload;
 }

stylix/darwin/fonts.nix

@@ -1,11 +1,7 @@
 { config, lib, ... }:
 
-let
-  cfg = config.stylix.fonts;
-in
 {
-  imports = [ ../fonts.nix ];
   config.fonts = lib.mkIf config.stylix.enable {
-    inherit (cfg) packages;
+    inherit (config.stylix.fonts) packages;
   };
 }

stylix/darwin/palette.nix

@@ -1,9 +1,6 @@
-args:
 { config, lib, ... }:
 
 {
-  imports = [ (import ../palette.nix args) ];
-
   config = lib.mkIf config.stylix.enable {
     environment.etc = config.stylix.generated.fileTree;
   };

stylix/hm/cursor.nix

@@ -10,8 +10,6 @@ let
 
 in
 {
-  imports = [ ../cursor.nix ];
-
   config = lib.mkIf (config.stylix.enable && pkgs.stdenv.hostPlatform.isLinux) {
     home.pointerCursor = {
       inherit (cfg) name package size;

stylix/hm/default.nix

@@ -1,19 +1,26 @@
 inputs:
-{ palette-generator, base16 }:
 { lib, ... }:
 
+# Imported modules which define new options must use an absolute path based
+# on ${inputs.self}, otherwise those options will not appear in the generated
+# documentation.
+
 let
   autoload = import ../autoload.nix { inherit lib inputs; } "hm";
 in
 {
   imports = [
-    ../pixel.nix
-    ../target.nix
-    ../opacity.nix
-    ./cursor.nix
-    ./fonts.nix
-    ./icon.nix
-    (import ./palette.nix { inherit palette-generator base16; })
+    "${inputs.self}/stylix/cursor.nix"
+    "${inputs.self}/stylix/fonts.nix"
+    "${inputs.self}/stylix/hm/cursor.nix"
+    "${inputs.self}/stylix/hm/fonts.nix"
+    "${inputs.self}/stylix/hm/icon.nix"
+    "${inputs.self}/stylix/hm/palette.nix"
+    "${inputs.self}/stylix/icon.nix"
+    "${inputs.self}/stylix/opacity.nix"
+    "${inputs.self}/stylix/palette.nix"
+    "${inputs.self}/stylix/pixel.nix"
+    "${inputs.self}/stylix/target.nix"
     (import ../templates.nix inputs)
   ] ++ autoload;
 }

stylix/hm/fonts.nix

@@ -4,7 +4,6 @@ let
   cfg = config.stylix.fonts;
 in
 {
-  imports = [ ../fonts.nix ];
   config = lib.mkIf config.stylix.enable {
     fonts.fontconfig.enable = true;
     home.packages = cfg.packages;

stylix/hm/icon.nix

@@ -5,7 +5,6 @@ let
   inherit (config.stylix) polarity;
 in
 {
-  imports = [ ../icon.nix ];
   config = lib.mkIf (config.stylix.enable && cfg.enable) {
     gtk = {
       iconTheme = {

stylix/hm/palette.nix

@@ -1,9 +1,6 @@
-args:
 { config, lib, ... }:
 
 {
-  imports = [ (import ../palette.nix args) ];
-
   config = lib.mkIf config.stylix.enable {
     xdg.configFile = config.stylix.generated.fileTree;
   };

stylix/home-manager-integration.nix

@@ -1,4 +1,3 @@
-homeManagerModule:
 {
   lib,
   config,
@@ -212,12 +211,20 @@ in
       default = true;
       example = false;
     };
+
+    module = lib.mkOption {
+      description = ''
+        The Home Manager module to be imported.
+      '';
+      internal = true;
+      readOnly = true;
+    };
   };
 
   config = lib.optionalAttrs (options ? home-manager) (
     lib.mkIf config.stylix.homeManagerIntegration.autoImport {
       home-manager.sharedModules =
-        [ homeManagerModule ]
+        [ config.stylix.homeManagerIntegration.module ]
         ++ (lib.optionals config.stylix.homeManagerIntegration.followSystem copyModules);
     }
   );

stylix/nixos/cursor.nix

@@ -1,11 +1,7 @@
 { config, lib, ... }:
 
-let
-  cfg = config.stylix.cursor;
-in
 {
-  imports = [ ../cursor.nix ];
   config = lib.mkIf config.stylix.enable {
-    environment.variables.XCURSOR_SIZE = toString cfg.size;
+    environment.variables.XCURSOR_SIZE = toString config.stylix.cursor.size;
   };
 }

stylix/nixos/default.nix

@@ -1,23 +1,25 @@
 inputs:
-{
-  palette-generator,
-  base16,
-  homeManagerModule,
-}:
 { lib, ... }:
 
+# Imported modules which define new options must use an absolute path based
+# on ${inputs.self}, otherwise those options will not appear in the generated
+# documentation.
+
 let
   autoload = import ../autoload.nix { inherit lib inputs; } "nixos";
 in
 {
   imports = [
-    ../pixel.nix
-    ../target.nix
-    ../opacity.nix
-    ./cursor.nix
-    ./fonts.nix
-    (import ./palette.nix { inherit palette-generator base16; })
+    "${inputs.self}/stylix/cursor.nix"
+    "${inputs.self}/stylix/fonts.nix"
+    "${inputs.self}/stylix/home-manager-integration.nix"
+    "${inputs.self}/stylix/nixos/cursor.nix"
+    "${inputs.self}/stylix/nixos/fonts.nix"
+    "${inputs.self}/stylix/nixos/palette.nix"
+    "${inputs.self}/stylix/opacity.nix"
+    "${inputs.self}/stylix/palette.nix"
+    "${inputs.self}/stylix/pixel.nix"
+    "${inputs.self}/stylix/target.nix"
     (import ../templates.nix inputs)
-    (import ../home-manager-integration.nix homeManagerModule)
   ] ++ autoload;
 }

stylix/nixos/fonts.nix

@@ -4,7 +4,6 @@ let
   cfg = config.stylix.fonts;
 in
 {
-  imports = [ ../fonts.nix ];
   config.fonts = lib.mkIf config.stylix.enable {
     inherit (cfg) packages;
 

stylix/nixos/palette.nix

@@ -1,9 +1,6 @@
-args:
 { config, lib, ... }:
 
 {
-  imports = [ (import ../palette.nix args) ];
-
   config = lib.mkIf config.stylix.enable {
     environment.etc = config.stylix.generated.fileTree;
   };

stylix/palette.nix

@@ -1,4 +1,3 @@
-{ palette-generator, base16 }:
 {
   pkgs,
   lib,
@@ -79,7 +78,7 @@ in
         # the output of the palette generator will not be protected from
         # garbage collection.
         default = pkgs.runCommand "palette.json" { } ''
-          ${palette-generator}/bin/palette-generator \
+          ${cfg.paletteGenerator}/bin/palette-generator \
             "${cfg.polarity}" \
             ${lib.escapeShellArg "${cfg.image}"} \
             "$out"
@@ -139,12 +138,25 @@ in
       type = lib.types.attrs;
       default = { };
     };
+
+    paletteGenerator = lib.mkOption {
+      description = "The palette generator executable.";
+      type = lib.types.package;
+      internal = true;
+      readOnly = true;
+    };
+
+    base16 = lib.mkOption {
+      description = "The base16.nix library.";
+      internal = true;
+      readOnly = true;
+    };
   };
 
   config = {
     # This attrset can be used like a function too, see
     # https://github.com/SenchoPens/base16.nix/blob/b390e87cd404e65ab4d786666351f1292e89162a/README.md#theme-step-22
-    lib.stylix.colors = (base16.mkSchemeAttrs cfg.base16Scheme).override cfg.override;
+    lib.stylix.colors = (cfg.base16.mkSchemeAttrs cfg.base16Scheme).override cfg.override;
 
     stylix.generated.fileTree = {
       # The raw output of the palette generator.

stylix/target.nix

@@ -42,6 +42,6 @@
       example = !autoEnable;
     }
     // lib.optionalAttrs autoEnable {
-      defaultText = lib.literalMD "same as [`stylix.autoEnable`](#stylixautoenable)";
+      defaultText = lib.literalMD "same as `stylix.autoEnable`";
     };
 }