doc: split modules into individual pages
This commit is contained in:
Daniel Thwaites
parent
e87bf16df9
commit
77e58881df
5 changed files with 148 additions and 59 deletions
157
docs/default.nix
157
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 = ''
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
<!-- The auto-generated list of modules will be added below. -->
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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. -->
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
# NixOS options
|
||||
# NixOS
|
||||
|
||||
The following options can only be set in a NixOS configuration.
|
||||
|
||||
Loading…
Add table
Add a link
Reference in a new issue