From 77e58881df26be44ce8d04c8dbd5d4f179f7eefe Mon Sep 17 00:00:00 2001 From: Daniel Thwaites Date: Mon, 17 Feb 2025 15:34:01 +0000 Subject: [PATCH] doc: split modules into individual pages --- docs/default.nix | 157 +++++++++++++----- docs/src/SUMMARY.md | 14 +- docs/src/configuration.md | 30 ++-- .../options/{hm.md => global/home_manager.md} | 4 +- docs/src/options/{ => global}/nixos.md | 2 +- 5 files changed, 148 insertions(+), 59 deletions(-) rename docs/src/options/{hm.md => global/home_manager.md} (81%) rename docs/src/options/{ => global}/nixos.md (88%) diff --git a/docs/default.nix b/docs/default.nix index 5f005cf6..bc782599 100644 --- a/docs/default.nix +++ b/docs/default.nix @@ -6,47 +6,82 @@ }: 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 = option: option // { - visible = option.visible && builtins.elemAt option.loc 0 == "stylix"; + visible = option.visible && lib.any pathFilter option.declarations; }; + }).optionsCommonMark; + + # The documentation for options which aren't linked to a specific module + makeGlobalOptionsDoc = + 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 { @@ -54,10 +89,63 @@ pkgs.stdenvNoCC.mkDerivation { src = ./.; 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/^## /### /' + + # The "declared by" links point to a file which only exists when the docs + # are built locally. This removes the links. + REMOVE_DECLARED_BY='/*Declared by:*/,/^$/d' + + function writeOptions() { + platformName="$1" + optionsFile="$2" + outputFile="$3" + + echo "## $platformName options" >>"$outputFile" + + if [ -s "$optionsFile" ]; then + sed -e "$REDUCE_HEADINGS" -e "$REMOVE_DECLARED_BY" <"$optionsFile" >>"$outputFile" + else + echo '*None provided.*' >>"$outputFile" + fi + } + + function writeModulePage() { + moduleName="$1" + homeManagerOptionsFile="$2" + nixosOptionsFile="$3" + + page="options/modules/$moduleName.md" + outputFile="src/$page" + + if [ ! -f "$file" ]; then + echo "# $moduleName" >>"$outputFile" + echo ${lib.escapeShellArg '' + > [!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" + + echo " - [$moduleName]($page)" >>src/SUMMARY.md + } + cp ${../README.md} src/README.md cp ${../gnome.png} src/gnome.png cp ${../kde.png} src/kde.png + mkdir -p src/options/global + writeOptions 'Home Manager' ${(makeGlobalOptionsDoc homeManagerConfiguration)} src/options/global/home_manager.md + writeOptions 'NixOS' ${(makeGlobalOptionsDoc nixosConfiguration)} src/options/global/nixos.md + + mkdir -p src/options/modules + ${modulePageScript} + # mdBook doesn't support this Markdown extension yet substituteInPlace **/*.md \ --replace-quiet '> [!NOTE]' '> **Note**' \ @@ -65,11 +153,6 @@ pkgs.stdenvNoCC.mkDerivation { --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 ''; buildPhase = '' diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 6fa96b6c..7e6e5a18 100644 --- a/docs/src/SUMMARY.md +++ b/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,12 @@ - [Adding modules](modules.md) - [Testbeds](testbeds.md) - [Style guide](styling.md) + +# Platforms + +- [Home Manager](options/global/home_manager.md) +- [NixOS](options/global/nixos.md) + +# Modules + + diff --git a/docs/src/configuration.md b/docs/src/configuration.md index 082e4c76..34cbd9c8 100644 --- a/docs/src/configuration.md +++ b/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 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. diff --git a/docs/src/options/hm.md b/docs/src/options/global/home_manager.md similarity index 81% rename from docs/src/options/hm.md rename to docs/src/options/global/home_manager.md index 99b63fef..cb37d2e3 100644 --- a/docs/src/options/hm.md +++ b/docs/src/options/global/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) diff --git a/docs/src/options/nixos.md b/docs/src/options/global/nixos.md similarity index 88% rename from docs/src/options/nixos.md rename to docs/src/options/global/nixos.md index bfb9de37..151d9c0a 100644 --- a/docs/src/options/nixos.md +++ b/docs/src/options/global/nixos.md @@ -1,4 +1,4 @@ -# NixOS options +# NixOS The following options can only be set in a NixOS configuration.