From 11f4e6c7e8b7ba80b4b872947ac5c8bbc5b8bbc5 Mon Sep 17 00:00:00 2001
From: yunfachi <yunfachi@gmail.com>
Date: Mon, 30 Sep 2024 15:38:40 +0300
Subject: [PATCH] docs/src/rices: init

---
 docs/.vitepress/config.mts        | 16 ++++++++
 docs/src/rices/examples.md        | 39 ++++++++++++++++++++
 docs/src/rices/introduction.md    | 61 +++++++++++++++++++++++++++++++
 docs/src/rices/structure.md       | 43 ++++++++++++++++++++++
 docs/src/ru/rices/examples.md     | 39 ++++++++++++++++++++
 docs/src/ru/rices/introduction.md | 61 +++++++++++++++++++++++++++++++
 docs/src/ru/rices/structure.md    | 44 ++++++++++++++++++++++
 7 files changed, 303 insertions(+)
 create mode 100644 docs/src/rices/examples.md
 create mode 100644 docs/src/rices/introduction.md
 create mode 100644 docs/src/rices/structure.md
 create mode 100644 docs/src/ru/rices/examples.md
 create mode 100644 docs/src/ru/rices/introduction.md
 create mode 100644 docs/src/ru/rices/structure.md

diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index 09d8380..6f5b9aa 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -64,6 +64,14 @@ function themeConfigEnglish() {return {
           { text: "Examples", link: "/hosts/examples" }
         ],
       },
+      {
+        text: "Rices",
+        items: [
+          { text: "Introduction", link: "/rices/introduction" },
+          { text: "Structure", link: "/rices/structure" },
+          { text: "Examples", link: "/rices/examples" }
+        ],
+      },
       { text: "Real Configurations", link: "/real-configurations" },
     ],
   }
@@ -109,6 +117,14 @@ function themeConfigRussian() {return {
           { text: "Примеры", link: "/ru/hosts/examples" }
         ],
       },
+      {
+        text: "Райсы",
+        items: [
+          { text: "Вступление", link: "/ru/rices/introduction" },
+          { text: "Структура", link: "/ru/rices/structure" },
+          { text: "Примеры", link: "/ru/rices/examples" }
+        ],
+      },
       { text: "Реальные конфигурации", link: "/real-configurations" },
     ],
   }
diff --git a/docs/src/rices/examples.md b/docs/src/rices/examples.md
new file mode 100644
index 0000000..59e6e6f
--- /dev/null
+++ b/docs/src/rices/examples.md
@@ -0,0 +1,39 @@
+# Examples {#examples}
+
+## Minimally Recommended Rice Module: {#minimally-recommended}
+An example of a minimal rice module configuration that serves as a baseline for all further settings:
+
+```nix
+delib.module {
+  name = "rices";
+
+  options = with delib; let
+    rice = {
+      options = riceSubmoduleOptions;
+    };
+  in {
+    rice = riceOption rice;
+    rices = ricesOption rice;
+  };
+
+  home.always = {myconfig, ...}: {
+    assertions = delib.riceNamesAssertions myconfig.rices;
+  };
+}
+```
+
+## Short Version {#short-version}
+Using `delib.riceNamesAssertions` is strongly recommended, but it can also be omitted.
+
+```nix
+delib.module {
+  name = "rices";
+
+  options = with delib; let
+    rice.options = riceSubmoduleOptions;
+  in {
+    rice = riceOption rice;
+    rices = ricesOption rice;
+  };
+}
+```
diff --git a/docs/src/rices/introduction.md b/docs/src/rices/introduction.md
new file mode 100644
index 0000000..7d25be0
--- /dev/null
+++ b/docs/src/rices/introduction.md
@@ -0,0 +1,61 @@
+# Introduction to Denix Rices {#introduction}
+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.
+
+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.
+
+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.
+
+## Inheritance {#inheritance}
+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.
+
+Example of three rices, where the first two inherit all configurations from the "rounded" rice:
+
+```nix
+delib.rice {
+  name = "black";
+  inherits = ["rounded"];
+  myconfig.colorscheme = "black";
+}
+```
+
+```nix
+delib.rice {
+  name = "light";
+  inherits = ["rounded"];
+  myconfig.colorscheme = "light";
+}
+```
+
+```nix
+delib.rice {
+  name = "rounded";
+  inheritanceOnly = true;
+  myconfig.hyprland.rounding = "6";
+}
+```
+
+## Options {#options}
+For rices to work, your configuration must include the options `${myconfigName}.rice` and `${myconfigName}.rices`, which **you define yourself** in one of the modules.
+
+Example of a minimal recommended configuration for rices:
+
+```nix
+delib.module {
+  name = "rices";
+
+  options = with delib; let
+    rice = {
+      options = riceSubmoduleOptions;
+    };
+  in {
+    rice = riceOption rice;
+    rices = ricesOption rice;
+  };
+
+  home.always = {myconfig, ...}: {
+    assertions = delib.riceNamesAssertions myconfig.rices;
+  };
+}
+```
+
+More examples can be found in the [Examples](/rices/examples) section.
diff --git a/docs/src/rices/structure.md b/docs/src/rices/structure.md
new file mode 100644
index 0000000..b15ad83
--- /dev/null
+++ b/docs/src/rices/structure.md
@@ -0,0 +1,43 @@
+# Structure {#structure}
+
+## Function Arguments {#function-arguments}
+- `name`: a string representing the rice name.
+- `inherits`: a list of strings - the names of rices whose configurations will be inherited by the current rice.  
+- `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.
+- `myconfig`: sets its value to `config.${myconfigName}` if `config.${myconfigName}.rice` matches the current rice.
+- `nixos`: sets its value to `config` if `isHomeManager` is `false` and `config.${myconfigName}.rice` matches the current rice.
+- `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}`.
+
+## Passed Arguments {#passed-arguments}
+A list of arguments passed to `[myconfig|nixos|home]` if their type is `lambda`:
+- `name`: the same `name` as in the arguments of `delib.rice`.
+- `myconfig`: equals `config.${myConfigName}`.
+- `cfg`: equals `config.${myConfigName}.rices.${delib.rice :: name}`.
+
+## Pseudocode {#pseudocode}
+```nix
+delib.rice {
+  name = "";
+
+  inherits = [];
+
+  inheritanceOnly = [];
+
+  # if config.${myconfigName}.rice == name
+  # then {config.${myConfigName} = ...;}
+  # else {}
+  myconfig = {name, cfg, myconfig, ...}: {};
+  
+  # if config.${myconfigName}.rice == name
+  # then {config = ...;}
+  # else {}
+  nixos = {name, cfg, myconfig, ...}: {};
+  
+  # if config.${myconfigName}.rice == name, then
+  #   if isHomeManager
+  #   then {config = ...;}
+  #   else {config.home-manager.users.${homeManagerUser} = ...;}
+  # else {}
+  home = {name, cfg, myconfig, ...}: {};
+}
+```
diff --git a/docs/src/ru/rices/examples.md b/docs/src/ru/rices/examples.md
new file mode 100644
index 0000000..dffb622
--- /dev/null
+++ b/docs/src/ru/rices/examples.md
@@ -0,0 +1,39 @@
+# Примеры {#examples}
+
+## Минимально рекомендуемый модуль райсов: {#minimally-recommended}
+Пример минимальной конфигурации модуля райсов, который является базовой точкой для всех дальнейших настроек:
+
+```nix
+delib.module {
+  name = "rices";
+
+  options = with delib; let
+    rice = {
+      options = riceSubmoduleOptions;
+    };
+  in {
+    rice = riceOption rice;
+    rices = ricesOption rice;
+  };
+
+  home.always = {myconfig, ...}: {
+    assertions = delib.riceNamesAssertions myconfig.rices;
+  };
+}
+```
+
+## Краткая версия {#short-version}
+Использование `delib.riceNamesAssertions` настоятельно рекомендуется, но можно обойтись и без него:
+
+```nix
+delib.module {
+  name = "rices";
+
+  options = with delib; let
+    rice.options = riceSubmoduleOptions;
+  in {
+    rice = riceOption rice;
+    rices = ricesOption rice;
+  };
+}
+```
diff --git a/docs/src/ru/rices/introduction.md b/docs/src/ru/rices/introduction.md
new file mode 100644
index 0000000..5e1d873
--- /dev/null
+++ b/docs/src/ru/rices/introduction.md
@@ -0,0 +1,61 @@
+# Введение в райсы Denix {#introduction}
+Райс (rice) - это attribute set, возвращаемый функцией [`delib.rice`](/ru/rices/structure), который включает или отключает определенные конфигурации в зависимости от значения опции `${myconfigName}.rice`. Также он передает входящий attribute set в функцию `delib.rice` в опцию `${myconfigName}.rice.${delib.rice :: name}`.
+
+Термин "райс" в жаргоне обозначает настройки системы, которые чаще всего связаны с внешним видом. В контексте Denix райс представляет собой конфигурацию, которую можно применить **к любому** хосту, и она будет работать корректно.
+
+При этом райсы не являются обязательными - если вы не хотите их использовать, просто не добавляйте опции `${myconfigName}.rices` и `${myconfigName}.rice`, а также не вызывайте функцию `delib.rice`.
+
+## Наследование {#inheritance}
+Райс может наследовать все конфигурации другого райса через атрибут `inherits`. Кроме того, можно установить `inheritanceOnly = true;`, чтобы скрыть райс от генерации в [`delib.system`](/TODO), оставив его только для наследования.
+
+Пример трех райсов, где первые два наследуют все конфигурации райса "rounded":
+
+```nix
+delib.rice {
+  name = "black";
+  inherits = ["rounded"];
+  myconfig.colorscheme = "black";
+}
+```
+
+```nix
+delib.rice {
+  name = "light";
+  inherits = ["rounded"];
+  myconfig.colorscheme = "light";
+}
+```
+
+```nix
+delib.rice {
+  name = "rounded";
+  inheritanceOnly = true;
+  myconfig.hyprland.rounding = "6";
+}
+```
+
+## Опции {#options}
+Для работы райсов ваша конфигурация должна включать опции `${myconfigName}.rice` и `${myconfigName}.rices`, которые **вы задаете самостоятельно** в одном из модулей.
+
+Пример минимальной рекомендуемой конфигурации для райсов:
+
+```nix
+delib.module {
+  name = "rices";
+
+  options = with delib; let
+    rice = {
+      options = riceSubmoduleOptions;
+    };
+  in {
+    rice = riceOption rice;
+    rices = ricesOption rice;
+  };
+
+  home.always = {myconfig, ...}: {
+    assertions = delib.riceNamesAssertions myconfig.rices;
+  };
+}
+```
+
+Другие примеры можно найти в разделе [Примеры](/ru/rices/examples). 
diff --git a/docs/src/ru/rices/structure.md b/docs/src/ru/rices/structure.md
new file mode 100644
index 0000000..a403841
--- /dev/null
+++ b/docs/src/ru/rices/structure.md
@@ -0,0 +1,44 @@
+# Структура {#structure}
+
+## Аргументы функции {#function-arguments}
+- `name`: строка, представляющая имя райса.
+- `inherits`: список строк - имена райсов, чьи конфигурации будут унаследованы текущим райсом.
+- `inheritanceOnly`: булевое значение (`true` или `false`), которое определяет, будет ли этот райс добавлен в [список систем, сгенерированный для каждого хоста и райса](/TODO), или же он используется только для наследования.
+- `myconfig`: устанавливает её значение в `config.${myconfigName}`, если `config.${myconfigName}.rice` соответствует текущему райсу.
+- `nixos`: устанавливает её значение в `config`, если `isHomeManager` равен `false` и `config.${myconfigName}.rice` соответствует текущему райсу.
+- `home`: устанавливает её значение в `config`, если `isHomeManager` равен `true` и `config.${myconfigName}.rice` соответствует текущему райсу. В противном случае, если `config.${myconfigName}.rice` соответствует текущему райсу, устанавливает её значение в `config.home-manager.users.${homeManagerUser}`.
+
+## Передаваемые аргументы {#passed-arguments}
+Список аргументов, которые передаются в `[myconfig|nixos|home]`, если их тип - `lambda`:
+
+- `name`: тот же `name`, что и в аргументах `delib.rice`.
+- `myconfig`: равен `config.${myConfigName}`.
+- `cfg`: равен `config.${myConfigName}.rices.${delib.rice :: name}`.
+
+## Псевдокод {#pseudocode}
+```nix
+delib.rice {
+  name = "";
+
+  inherits = [];
+
+  inheritanceOnly = [];
+
+  # если config.${myconfigName}.rice == name
+  # то {config.${myConfigName} = ...;}
+  # иначе {}
+  myconfig = {name, cfg, myconfig, ...}: {};
+
+  # если config.${myconfigName}.rice == name
+  # то {config = ...;}
+  # иначе {}
+  nixos = {name, cfg, myconfig, ...}: {};
+
+  # если config.${myconfigName}.rice == name, то
+  #   если isHomeManager
+  #   то {config = ...;}
+  #   иначе {config.home-manager.users.${homeManagerUser} = ...;}
+  # иначе {}
+  home = {name, cfg, myconfig, ...}: {};
+}
+```