Skip to content

Commit 11f4e6c

Browse files
yunfachiyunfachi
committed
docs/src/rices: init
1 parent 1cb6dd0 commit 11f4e6c

File tree

7 files changed

+303
-0
lines changed

7 files changed

+303
-0
lines changed

‎docs/.vitepress/config.mts‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,14 @@ function themeConfigEnglish() {return {
6464
{ text: "Examples", link: "/hosts/examples" }
6565
],
6666
},
67+
{
68+
text: "Rices",
69+
items: [
70+
{ text: "Introduction", link: "/rices/introduction" },
71+
{ text: "Structure", link: "/rices/structure" },
72+
{ text: "Examples", link: "/rices/examples" }
73+
],
74+
},
6775
{ text: "Real Configurations", link: "/real-configurations" },
6876
],
6977
}
@@ -109,6 +117,14 @@ function themeConfigRussian() {return {
109117
{ text: "Примеры", link: "/ru/hosts/examples" }
110118
],
111119
},
120+
{
121+
text: "Райсы",
122+
items: [
123+
{ text: "Вступление", link: "/ru/rices/introduction" },
124+
{ text: "Структура", link: "/ru/rices/structure" },
125+
{ text: "Примеры", link: "/ru/rices/examples" }
126+
],
127+
},
112128
{ text: "Реальные конфигурации", link: "/real-configurations" },
113129
],
114130
}

‎docs/src/rices/examples.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Examples {#examples}
2+
3+
## Minimally Recommended Rice Module: {#minimally-recommended}
4+
An example of a minimal rice module configuration that serves as a baseline for all further settings:
5+
6+
```nix
7+
delib.module {
8+
name = "rices";
9+
10+
options = with delib; let
11+
rice = {
12+
options = riceSubmoduleOptions;
13+
};
14+
in {
15+
rice = riceOption rice;
16+
rices = ricesOption rice;
17+
};
18+
19+
home.always = {myconfig, ...}: {
20+
assertions = delib.riceNamesAssertions myconfig.rices;
21+
};
22+
}
23+
```
24+
25+
## Short Version {#short-version}
26+
Using `delib.riceNamesAssertions` is strongly recommended, but it can also be omitted.
27+
28+
```nix
29+
delib.module {
30+
name = "rices";
31+
32+
options = with delib; let
33+
rice.options = riceSubmoduleOptions;
34+
in {
35+
rice = riceOption rice;
36+
rices = ricesOption rice;
37+
};
38+
}
39+
```

‎docs/src/rices/introduction.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Introduction to Denix Rices {#introduction}
2+
A rice is an attribute set returned by the function [`delib.rice`](/rices/structure), which enables or disables specific configurations depending on the value of the option `${myconfigName}.rice`. It also passes the input attribute set of the `delib.rice` function to the `${myconfigName}.rice.${delib.rice :: name}` option.
3+
4+
The term "rice" in slang refers to system settings, usually related to appearance. In the Denix context, a rice represents a configuration that can be applied **to any** host and will function correctly.
5+
6+
However, rices are not mandatory: to avoid using them, simply do not add the options `${myconfigName}.rices` and `${myconfigName}.rice`, and do not use the `delib.rice` function.
7+
8+
## Inheritance {#inheritance}
9+
A rice can inherit all configurations of another rice via the `inherits` attribute. Additionally, you can set `inheritanceOnly = true;`, which will hide the rice from being generated in [`delib.system`](/TODO), leaving it only for inheritance.
10+
11+
Example of three rices, where the first two inherit all configurations from the "rounded" rice:
12+
13+
```nix
14+
delib.rice {
15+
name = "black";
16+
inherits = ["rounded"];
17+
myconfig.colorscheme = "black";
18+
}
19+
```
20+
21+
```nix
22+
delib.rice {
23+
name = "light";
24+
inherits = ["rounded"];
25+
myconfig.colorscheme = "light";
26+
}
27+
```
28+
29+
```nix
30+
delib.rice {
31+
name = "rounded";
32+
inheritanceOnly = true;
33+
myconfig.hyprland.rounding = "6";
34+
}
35+
```
36+
37+
## Options {#options}
38+
For rices to work, your configuration must include the options `${myconfigName}.rice` and `${myconfigName}.rices`, which **you define yourself** in one of the modules.
39+
40+
Example of a minimal recommended configuration for rices:
41+
42+
```nix
43+
delib.module {
44+
name = "rices";
45+
46+
options = with delib; let
47+
rice = {
48+
options = riceSubmoduleOptions;
49+
};
50+
in {
51+
rice = riceOption rice;
52+
rices = ricesOption rice;
53+
};
54+
55+
home.always = {myconfig, ...}: {
56+
assertions = delib.riceNamesAssertions myconfig.rices;
57+
};
58+
}
59+
```
60+
61+
More examples can be found in the [Examples](/rices/examples) section.

‎docs/src/rices/structure.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Structure {#structure}
2+
3+
## Function Arguments {#function-arguments}
4+
- `name`: a string representing the rice name.
5+
- `inherits`: a list of strings - the names of rices whose configurations will be inherited by the current rice.
6+
- `inheritanceOnly`: a boolean value that determines whether this rice will be added to the [list of systems generated for each host and rice](/TODO), or if it is only used for inheritance.
7+
- `myconfig`: sets its value to `config.${myconfigName}` if `config.${myconfigName}.rice` matches the current rice.
8+
- `nixos`: sets its value to `config` if `isHomeManager` is `false` and `config.${myconfigName}.rice` matches the current rice.
9+
- `home`: sets its value to `config` if `isHomeManager` is `true` and `config.${myconfigName}.rice` matches the current rice. Otherwise, if `config.${myconfigName}.rice` matches the current rice, sets its value to `config.home-manager.users.${homeManagerUser}`.
10+
11+
## Passed Arguments {#passed-arguments}
12+
A list of arguments passed to `[myconfig|nixos|home]` if their type is `lambda`:
13+
- `name`: the same `name` as in the arguments of `delib.rice`.
14+
- `myconfig`: equals `config.${myConfigName}`.
15+
- `cfg`: equals `config.${myConfigName}.rices.${delib.rice :: name}`.
16+
17+
## Pseudocode {#pseudocode}
18+
```nix
19+
delib.rice {
20+
name = "";
21+
22+
inherits = [];
23+
24+
inheritanceOnly = [];
25+
26+
# if config.${myconfigName}.rice == name
27+
# then {config.${myConfigName} = ...;}
28+
# else {}
29+
myconfig = {name, cfg, myconfig, ...}: {};
30+
31+
# if config.${myconfigName}.rice == name
32+
# then {config = ...;}
33+
# else {}
34+
nixos = {name, cfg, myconfig, ...}: {};
35+
36+
# if config.${myconfigName}.rice == name, then
37+
# if isHomeManager
38+
# then {config = ...;}
39+
# else {config.home-manager.users.${homeManagerUser} = ...;}
40+
# else {}
41+
home = {name, cfg, myconfig, ...}: {};
42+
}
43+
```

‎docs/src/ru/rices/examples.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Примеры {#examples}
2+
3+
## Минимально рекомендуемый модуль райсов: {#minimally-recommended}
4+
Пример минимальной конфигурации модуля райсов, который является базовой точкой для всех дальнейших настроек:
5+
6+
```nix
7+
delib.module {
8+
name = "rices";
9+
10+
options = with delib; let
11+
rice = {
12+
options = riceSubmoduleOptions;
13+
};
14+
in {
15+
rice = riceOption rice;
16+
rices = ricesOption rice;
17+
};
18+
19+
home.always = {myconfig, ...}: {
20+
assertions = delib.riceNamesAssertions myconfig.rices;
21+
};
22+
}
23+
```
24+
25+
## Краткая версия {#short-version}
26+
Использование `delib.riceNamesAssertions` настоятельно рекомендуется, но можно обойтись и без него:
27+
28+
```nix
29+
delib.module {
30+
name = "rices";
31+
32+
options = with delib; let
33+
rice.options = riceSubmoduleOptions;
34+
in {
35+
rice = riceOption rice;
36+
rices = ricesOption rice;
37+
};
38+
}
39+
```

‎docs/src/ru/rices/introduction.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Введение в райсы Denix {#introduction}
2+
Райс (rice) - это attribute set, возвращаемый функцией [`delib.rice`](/ru/rices/structure), который включает или отключает определенные конфигурации в зависимости от значения опции `${myconfigName}.rice`. Также он передает входящий attribute set в функцию `delib.rice` в опцию `${myconfigName}.rice.${delib.rice :: name}`.
3+
4+
Термин "райс" в жаргоне обозначает настройки системы, которые чаще всего связаны с внешним видом. В контексте Denix райс представляет собой конфигурацию, которую можно применить **к любому** хосту, и она будет работать корректно.
5+
6+
При этом райсы не являются обязательными - если вы не хотите их использовать, просто не добавляйте опции `${myconfigName}.rices` и `${myconfigName}.rice`, а также не вызывайте функцию `delib.rice`.
7+
8+
## Наследование {#inheritance}
9+
Райс может наследовать все конфигурации другого райса через атрибут `inherits`. Кроме того, можно установить `inheritanceOnly = true;`, чтобы скрыть райс от генерации в [`delib.system`](/TODO), оставив его только для наследования.
10+
11+
Пример трех райсов, где первые два наследуют все конфигурации райса "rounded":
12+
13+
```nix
14+
delib.rice {
15+
name = "black";
16+
inherits = ["rounded"];
17+
myconfig.colorscheme = "black";
18+
}
19+
```
20+
21+
```nix
22+
delib.rice {
23+
name = "light";
24+
inherits = ["rounded"];
25+
myconfig.colorscheme = "light";
26+
}
27+
```
28+
29+
```nix
30+
delib.rice {
31+
name = "rounded";
32+
inheritanceOnly = true;
33+
myconfig.hyprland.rounding = "6";
34+
}
35+
```
36+
37+
## Опции {#options}
38+
Для работы райсов ваша конфигурация должна включать опции `${myconfigName}.rice` и `${myconfigName}.rices`, которые **вы задаете самостоятельно** в одном из модулей.
39+
40+
Пример минимальной рекомендуемой конфигурации для райсов:
41+
42+
```nix
43+
delib.module {
44+
name = "rices";
45+
46+
options = with delib; let
47+
rice = {
48+
options = riceSubmoduleOptions;
49+
};
50+
in {
51+
rice = riceOption rice;
52+
rices = ricesOption rice;
53+
};
54+
55+
home.always = {myconfig, ...}: {
56+
assertions = delib.riceNamesAssertions myconfig.rices;
57+
};
58+
}
59+
```
60+
61+
Другие примеры можно найти в разделе [Примеры](/ru/rices/examples).

‎docs/src/ru/rices/structure.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Структура {#structure}
2+
3+
## Аргументы функции {#function-arguments}
4+
- `name`: строка, представляющая имя райса.
5+
- `inherits`: список строк - имена райсов, чьи конфигурации будут унаследованы текущим райсом.
6+
- `inheritanceOnly`: булевое значение (`true` или `false`), которое определяет, будет ли этот райс добавлен в [список систем, сгенерированный для каждого хоста и райса](/TODO), или же он используется только для наследования.
7+
- `myconfig`: устанавливает её значение в `config.${myconfigName}`, если `config.${myconfigName}.rice` соответствует текущему райсу.
8+
- `nixos`: устанавливает её значение в `config`, если `isHomeManager` равен `false` и `config.${myconfigName}.rice` соответствует текущему райсу.
9+
- `home`: устанавливает её значение в `config`, если `isHomeManager` равен `true` и `config.${myconfigName}.rice` соответствует текущему райсу. В противном случае, если `config.${myconfigName}.rice` соответствует текущему райсу, устанавливает её значение в `config.home-manager.users.${homeManagerUser}`.
10+
11+
## Передаваемые аргументы {#passed-arguments}
12+
Список аргументов, которые передаются в `[myconfig|nixos|home]`, если их тип - `lambda`:
13+
14+
- `name`: тот же `name`, что и в аргументах `delib.rice`.
15+
- `myconfig`: равен `config.${myConfigName}`.
16+
- `cfg`: равен `config.${myConfigName}.rices.${delib.rice :: name}`.
17+
18+
## Псевдокод {#pseudocode}
19+
```nix
20+
delib.rice {
21+
name = "";
22+
23+
inherits = [];
24+
25+
inheritanceOnly = [];
26+
27+
# если config.${myconfigName}.rice == name
28+
# то {config.${myConfigName} = ...;}
29+
# иначе {}
30+
myconfig = {name, cfg, myconfig, ...}: {};
31+
32+
# если config.${myconfigName}.rice == name
33+
# то {config = ...;}
34+
# иначе {}
35+
nixos = {name, cfg, myconfig, ...}: {};
36+
37+
# если config.${myconfigName}.rice == name, то
38+
# если isHomeManager
39+
# то {config = ...;}
40+
# иначе {config.home-manager.users.${homeManagerUser} = ...;}
41+
# иначе {}
42+
home = {name, cfg, myconfig, ...}: {};
43+
}
44+
```

0 commit comments

Comments
 (0)