docs/src/options: init

Author: yunfachi

docs/.vitepress/config.mts

@@ -59,6 +59,12 @@ function themeConfigEnglish() {return {
           { text: "Examples", link: "/modules/examples" }
         ],
       },
+      {
+        text: "Options",
+        items: [
+          { text: "Introduction", link: "/options/introduction" },
+        ],
+      },
       {
         text: "Hosts",
         items: [
@@ -112,6 +118,12 @@ function themeConfigRussian() {return {
           { text: "Примеры", link: "/ru/modules/examples" }
         ],
       },
+      {
+        text: "Опции",
+        items: [
+          { text: "Вступление", link: "/ru/options/introduction" },
+        ],
+      },
       {
         text: "Хосты",
         items: [

docs/src/modules/introduction-nixos.md

@@ -101,7 +101,7 @@ delib.module {
 }
 ```
 
-For more information on Denix options, see the [Options](/TODO) section.
+For more information on Denix options, see the [Options](/options/introduction) section.
 
 ## Creating Your Own Modules (Options) {#creating-own-modules}
 Declaring your own options is a great practice if you want to enable or disable certain parts of the code. This can be useful if you have multiple hosts (machines) with the same configuration, and, for example, machine `foo` does not need a program that is used on machine `bar`.

docs/src/modules/introduction.md

@@ -31,6 +31,6 @@ This means that you can use all three types of modules simultaneously, although
 ## Simplicity and Cleanliness {#simplicity-and-cleanliness}
 Denix modules tend to look simpler and cleaner compared to NixOS/Home Manager modules, due to the following reasons:
 
-1. Simple yet fully functional option declaration (see [Options](/TODO)).
+1. Simple yet fully functional option declaration (see [Options](/options/introduction)).
 2. Built-in logic for separating configurations based on the value of `${delib.module :: name}.enable`: always, ifEnabled, ifDisabled.
 3. Shared options but separated configurations for NixOS, Home Manager, and custom options.

docs/src/modules/structure.md

@@ -3,7 +3,7 @@ This section uses the variables `myconfigName`, `isHomeManager`, and `homeManage
 
 ## Function Arguments {#function-arguments}
 - `name`{#function-arguments-name}: string. It is recommended that it matches the parent path of the module's `enable` option, such as `"programs.example"`, since the `cfg` argument depends on this path.
-- `options`: attrset or a lambda that returns an attrset (see [Options](/TODO)).
+- `options`: attrset or a lambda that returns an attrset (see [Options](/options/introduction)).
 - `[myconfig|nixos|home].[ifEnabled|ifDisabled|always]`: attrset or a lambda that returns an attrset.
 - `myconfig.*`: sets values in `config.${myconfigName}`.
 - `nixos.*`: sets values in `config` if `isHomeManager` is `false`; otherwise, it does nothing.

docs/src/options/introduction.md

@@ -0,0 +1,59 @@
+# Introduction to Denix Options {#introduction}
+Denix options are a wrapper for `lib.mkOption`. This means that any Denix option can be created using the standard `lib.mkOption`, and using Denix options is optional.
+
+## Why use Denix options? {#why}
+Using `lib.mkOption` can be cumbersome, and writing something like this every time:
+
+```nix
+lib.mkOption {type = lib.types.listOf lib.types.str; default = [];}
+```
+
+is inconvenient, especially when options are used extensively in your configuration. Instead, you can write something more concise:
+
+```nix
+delib.listOfOption delib.str []
+```
+
+Thus, instead of creating an option by specifying all parameters, you can use Denix functions for more readable and cleaner code.
+
+## Working Principle {#principle}
+Functions related to options are divided into four main types:
+
+### Creating an Option with Type N
+- `*Option <default>` - for example, `strOption "foo"`.
+- `*OfOption <secondType> <default>` - for example, `listOfOption str ["foo" "bar"]`.
+- `*ToOption <secondType> <default>` - for example, `lambdaToOption int (x: 123)`.
+
+### Adding Type N to Option Type X
+- `allow* <option>` - for example, `allowStr ...`.
+- `allow*Of <secondType> <option>` - for example, `allowListOf str ...`.
+- `allow*To <secondType> <option>` - for example, `allowLambdaTo int ...`.
+
+### Directly Modifying the Attribute Set of an Option
+- `noDefault <option>` - removes the `default` attribute from the option. It is rarely used since options without a default value are uncommon.
+- `readOnly <option>` - adds the `readOnly` attribute with the value `true`.
+- `apply <option> <apply>` - adds the `apply` attribute with the value passed to this function.
+- `description <option> <description>` - adds the `description` attribute with the given value.
+
+### Generating Specific Options
+- `singleEnableOption <default> {name, ...}` - creates an attribute set using the expression `delib.setAttrByStrPath "${name}.enable" (boolOption default)`. This is commonly used in `delib.module :: options` with its [passed arguments](/modules/structure#passed-arguments), so you can simply write:
+
+```nix
+options = delib.singleEnableOption <default>;
+```
+
+The list of current options can be found in the source code: [github:yunfachi/denix?path=lib/options.nix](https://github.com/yunfachi/denix/blob/master/lib/options.nix)
+
+## Examples {#examples}
+
+| Denix                                      | lib.mkOption                                                 |
+|--------------------------------------------|--------------------------------------------------------------|
+| `portOption 22`                            | `mkOption {type = types.port; default = 22;}`                |
+| `noDefault (portOption null)`              | `mkOption {type = types.port;}`                              |
+| `allowNull (portOption null)`              | `mkOption {type = types.nullOr types.port; default = null;}` |
+| `allowStr (portOption "22")`               | `mkOption {type = types.strOr types.port; default = "22";}`  |
+| `listOfOption port []`                     | `mkOption {type = types.listOf types.port; default = [];}`   |
+| `readOnly (noDefault (portOption null))`   | `mkOption {type = types.port; readOnly = true;}`             |
+| `singleEnableOption true {name = "git";}`  | `git.enable = mkEnableOption "git" // {default = true;}`     |
+
+> *(Usually `{name = "git";}` is not required, as this function is mainly used in `delib.module :: options`)*

docs/src/ru/modules/introduction-nixos.md

@@ -99,7 +99,7 @@ optionName = lib.mkOption {
 }
 ```
 
-Более подробно о опциях Denix можно узнать в разделе [Опции](/TODO).
+Более подробно о опциях Denix можно узнать в разделе [Опции](/ru/options/introduction).
 
 ## Создание своих модулей (опций) {#creating-own-modules}
 Декларирование своих опций - отличная практика, если вы хотите включать и отключать части кода. Это может понадобиться, если у вас несколько хостов (машин) с одной конфигурацией, и, например, машине `foo` не нужна программа, которая используется на машине `bar`.

docs/src/ru/modules/introduction.md

@@ -31,6 +31,6 @@
 ## Простота и чистота {#simplicity-and-cleanliness}
 Модули Denix в большинстве случаев выглядят проще и чище, чем модули NixOS/Home Manager, по следующим причинам:
 
-1. Простое, но при этом полноценное декларирование опций (см. [Опции](/TODO)).
+1. Простое, но при этом полноценное декларирование опций (см. [Опции](/ru/options/introduction)).
 2. Встроенная логика разделения конфигураций в зависимости от значения опции `${delib.module :: name}.enable`: always, ifEnabled, ifDisabled.
 3. Общие опции, но разделённые конфигурации для NixOS, Home Manager и собственных опций.

docs/src/ru/modules/structure.md

@@ -3,7 +3,7 @@
 
 ## Аргументы функции {#function-arguments}
 - `name`{#function-arguments-name}: строка. Рекомендуется, чтобы она совпадала с родительским путём опции `enable` модуля, например, `"programs.example"`, так как передаваемый аргумент `cfg` зависит именно от этого пути.
-- `options`: attrset или lambda, которая возвращает attrset (см. [Опции](/TODO)).
+- `options`: attrset или lambda, которая возвращает attrset (см. [Опции](/ru/options/introduction)).
 - `[myconfig|nixos|home].[ifEnabled|ifDisabled|always]`: attrset или lambda, которая возвращает attrset.
 - `myconfig.*`: устанавливает значения в `config.${myconfigName}`.
 - `nixos.*`: устанавливает значения в `config`, если `isHomeManager` равен `false`, иначе не выполняется.

docs/src/ru/options/introduction.md

@@ -0,0 +1,59 @@
+# Введение в опции Denix {#introduction}
+Опции Denix представляют собой обёртку для `lib.mkOption`. Это означает, что любую опцию Denix можно создать, используя стандартный `lib.mkOption`, и использование опций Denix является необязательным.
+
+## Зачем использовать опции Denix? {#why}
+Использование `lib.mkOption` может быть громоздким, и каждый раз писать что-то вроде: 
+
+```nix
+lib.mkOption {type = lib.types.listOf lib.types.str; default = [];}
+```
+
+- неудобно, особенно когда опции в вашей конфигурации используются повсеместно. Вместо этого можно написать более лаконично:
+
+```nix
+delib.listOfOption delib.str []
+```
+
+Таким образом, вместо создания опции через указание всех параметров, можно использовать функции Denix для более читабельного и аккуратного кода.
+
+## Принцип работы {#principle}
+Функции, связанные с опциями, делятся на четыре основных типа:
+
+### Создание опции с типом N
+- `*Option <default>` - например, `strOption "foo"`.
+- `*OfOption <secondType> <default>` - например, `listOfOption str ["foo" "bar"]`.
+- `*ToOption <secondType> <default>` - например, `lambdaToOption int (x: 123)`.
+
+### Добавление к типам опции X тип N
+- `allow* <option>` - например, `allowStr ...`.
+- `allow*Of <secondType> <option>` - например, `allowListOf str ...`.
+- `allow*To <secondType> <option>` - например, `allowLambdaTo int ...`.
+
+### Прямое изменение attribute set опции
+- `noDefault <option>` - удаляет атрибут `default` из опции. Используется редко, так как редко бывают опции без значения по умолчанию.
+- `readOnly <option>` - добавляет атрибут `readOnly` со значением `true`.
+- `apply <option> <apply>` - добавляет атрибут `apply` с переданным значением.
+- `description <option> <description>` - добавляет атрибут `description` с переданным значением.
+
+### Генерация конкретной опции/опций
+- `singleEnableOption <default> {name, ...}` - создаёт attribute set с помощью выражения `delib.setAttrByStrPath "${name}.enable" (boolOption default)`. Обычно это используется в `delib.module :: options`, с её [передаваемыми аргументами](/ru/modules/structure#passed-arguments), поэтому достаточно написать:
+
+  ```nix
+  options = delib.singleEnableOption <default>;
+  ```
+
+Список актуальных опций можно найти в исходном коде: [github:yunfachi/denix?path=lib/options.nix](https://github.com/yunfachi/denix/blob/master/lib/options.nix)
+
+## Примеры {#examples}
+
+| Denix                                      | lib.mkOption                                                 |
+|--------------------------------------------|--------------------------------------------------------------|
+| `portOption 22`                            | `mkOption {type = types.port; default = 22;}`                |
+| `noDefault (portOption null)`              | `mkOption {type = types.port;}`                              |
+| `allowNull (portOption null)`              | `mkOption {type = types.nullOr types.port; default = null;}` |
+| `allowStr (portOption "22")`               | `mkOption {type = types.strOr types.port; default = "22";}`  |
+| `listOfOption port []`                     | `mkOption {type = types.listOf types.port; default = [];}`   |
+| `readOnly (noDefault (portOption null))`   | `mkOption {type = types.port; readOnly = true;}`             |
+| `singleEnableOption true {name = "git";}`  | `git.enable = mkEnableOption "git" // {default = true;}`     |
+
+> *(Обычно `{name = "git";}` указывать не требуется, так как эта функция в основном используется в `delib.module :: options`)*