doc: split modules into separate pages

docs/book.toml

@@ -2,8 +2,18 @@
 title = "Stylix"
 language = "en"
 
+[preprocessor.alerts]
+
 [output.html]
 site-url = "/stylix/"
 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
+  nixosConfiguration = lib.nixosSystem {
+    inherit (pkgs) system;
+    modules = [
+      inputs.home-manager.nixosModules.home-manager
+      inputs.self.nixosModules.stylix
+      ./settings.nix
+    ];
+  };
+
+  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:
-    pkgs.nixosOptionsDoc {
+    { configuration, pathFilter }:
+    (pkgs.nixosOptionsDoc {
       inherit (configuration) options;
-
-      # Filter out any options not beginning with `stylix`
       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
-      ];
-    }
-  );
-
-  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";
-          };
-        }
-      ];
-    }
-  );
+  # 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");
+
+  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**'
-
-    # 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/platforms
+    writeOptions 'Home Manager' ${(makePlatformsOptionsDoc homeManagerConfiguration)} src/options/platforms/home_manager.md
+    writeOptions 'NixOS' ${(makePlatformsOptionsDoc nixosConfiguration)} src/options/platforms/nixos.md
 
-  buildPhase = ''
-    ${pkgs.mdbook}/bin/mdbook build --dest-dir $out
+    mkdir --parents src/options/modules
+    ${modulePageScript}
   '';
+
+  buildPhase = "mdbook build --dest-dir $out";
 }

docs/src/SUMMARY.md

@@ -6,15 +6,23 @@
 - [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)
 - [Development Environment](development_environment.md)
 - [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/hm.md → 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/nixos.md → docs/src/options/platforms/nixos.md

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