diff options
author | pennae <github@quasiparticle.net> | 2023-03-08 09:15:48 +0100 |
---|---|---|
committer | pennae <82953136+pennae@users.noreply.github.com> | 2023-05-03 19:58:21 +0200 |
commit | 407f6196a23f8b0b42c74c66f2717645aa277bbd (patch) | |
tree | 86719c58cfa4ac8e035b49e263238d302df13ba7 /nixos/doc/manual | |
parent | 69259eec2334d066e3a6563ced278c283a618a2d (diff) |
nixos-render-docs: add examples support
the nixos manual contains enough examples to support them as a proper toc entity with specialized rendering, and if in the future the nixpkgs wants to use nixos-render-docs we will definitely have to support them. this also allows us to restore some examples that were lost in previous translation steps because there were too few to add renderer support back then.
Diffstat (limited to 'nixos/doc/manual')
6 files changed, 26 insertions, 22 deletions
diff --git a/nixos/doc/manual/development/freeform-modules.section.md b/nixos/doc/manual/development/freeform-modules.section.md index 514a06f97ee77..4f344dd804601 100644 --- a/nixos/doc/manual/development/freeform-modules.section.md +++ b/nixos/doc/manual/development/freeform-modules.section.md @@ -13,7 +13,7 @@ checking for entire option trees, it is only recommended for use in submodules. ::: {#ex-freeform-module .example} -**Example: Freeform submodule** +### Freeform submodule The following shows a submodule assigning a freeform type that allows arbitrary attributes with `str` values below `settings`, but also diff --git a/nixos/doc/manual/development/option-declarations.section.md b/nixos/doc/manual/development/option-declarations.section.md index f6fed3e16837f..3448b07722b85 100644 --- a/nixos/doc/manual/development/option-declarations.section.md +++ b/nixos/doc/manual/development/option-declarations.section.md @@ -77,6 +77,7 @@ The option's description is "Whether to enable \<name\>.". For example: ::: {#ex-options-declarations-util-mkEnableOption-magic .example} +### `mkEnableOption` usage ```nix lib.mkEnableOption (lib.mdDoc "magic") # is like @@ -126,6 +127,7 @@ During the transition to CommonMark documentation `mkPackageOption` creates an o Examples: ::: {#ex-options-declarations-util-mkPackageOption-hello .example} +### Simple `mkPackageOption` usage ```nix lib.mkPackageOptionMD pkgs "hello" { } # is like @@ -139,6 +141,7 @@ lib.mkOption { ::: ::: {#ex-options-declarations-util-mkPackageOption-ghc .example} +### `mkPackageOption` with explicit default and example ```nix lib.mkPackageOptionMD pkgs "GHC" { default = [ "ghc" ]; @@ -156,6 +159,7 @@ lib.mkOption { ::: ::: {#ex-options-declarations-util-mkPackageOption-extraDescription .example} +### `mkPackageOption` with additional description text ```nix mkPackageOption pkgs [ "python39Packages" "pytorch" ] { extraDescription = "This is an example and doesn't actually do anything."; @@ -217,7 +221,7 @@ changing the main service module file and the type system automatically enforces that there can only be a single display manager enabled. ::: {#ex-option-declaration-eot-service .example} -**Example: Extensible type placeholder in the service module** +### Extensible type placeholder in the service module ```nix services.xserver.displayManager.enable = mkOption { description = "Display manager to use"; @@ -227,7 +231,7 @@ services.xserver.displayManager.enable = mkOption { ::: ::: {#ex-option-declaration-eot-backend-gdm .example} -**Example: Extending `services.xserver.displayManager.enable` in the `gdm` module** +### Extending `services.xserver.displayManager.enable` in the `gdm` module ```nix services.xserver.displayManager.enable = mkOption { type = with types; nullOr (enum [ "gdm" ]); @@ -236,7 +240,7 @@ services.xserver.displayManager.enable = mkOption { ::: ::: {#ex-option-declaration-eot-backend-sddm .example} -**Example: Extending `services.xserver.displayManager.enable` in the `sddm` module** +### Extending `services.xserver.displayManager.enable` in the `sddm` module ```nix services.xserver.displayManager.enable = mkOption { type = with types; nullOr (enum [ "sddm" ]); diff --git a/nixos/doc/manual/development/option-types.section.md b/nixos/doc/manual/development/option-types.section.md index 51977c58333f9..9e2ecb8e35626 100644 --- a/nixos/doc/manual/development/option-types.section.md +++ b/nixos/doc/manual/development/option-types.section.md @@ -36,7 +36,7 @@ merging is handled. together. This type is recommended when the option type is unknown. ::: {#ex-types-anything .example} - **Example: `types.anything` Example** + ### `types.anything` Two definitions of this type like @@ -356,7 +356,7 @@ you will still need to provide a default value (e.g. an empty attribute set) if you want to allow users to leave it undefined. ::: {#ex-submodule-direct .example} -**Example: Directly defined submodule** +### Directly defined submodule ```nix options.mod = mkOption { description = "submodule example"; @@ -375,7 +375,7 @@ options.mod = mkOption { ::: ::: {#ex-submodule-reference .example} -**Example: Submodule defined as a reference** +### Submodule defined as a reference ```nix let modOptions = { @@ -403,7 +403,7 @@ multiple definitions of the submodule option set ([Example: Definition of a list of submodules](#ex-submodule-listof-definition)). ::: {#ex-submodule-listof-declaration .example} -**Example: Declaration of a list of submodules** +### Declaration of a list of submodules ```nix options.mod = mkOption { description = "submodule example"; @@ -422,7 +422,7 @@ options.mod = mkOption { ::: ::: {#ex-submodule-listof-definition .example} -**Example: Definition of a list of submodules** +### Definition of a list of submodules ```nix config.mod = [ { foo = 1; bar = "one"; } @@ -437,7 +437,7 @@ multiple named definitions of the submodule option set ([Example: Definition of attribute sets of submodules](#ex-submodule-attrsof-definition)). ::: {#ex-submodule-attrsof-declaration .example} -**Example: Declaration of attribute sets of submodules** +### Declaration of attribute sets of submodules ```nix options.mod = mkOption { description = "submodule example"; @@ -456,7 +456,7 @@ options.mod = mkOption { ::: ::: {#ex-submodule-attrsof-definition .example} -**Example: Definition of attribute sets of submodules** +### Definition of attribute sets of submodules ```nix config.mod.one = { foo = 1; bar = "one"; }; config.mod.two = { foo = 2; bar = "two"; }; @@ -476,7 +476,7 @@ Types are mainly characterized by their `check` and `merge` functions. ([Example: Overriding a type check](#ex-extending-type-check-2)). ::: {#ex-extending-type-check-1 .example} - **Example: Adding a type check** + ### Adding a type check ```nix byte = mkOption { @@ -487,7 +487,7 @@ Types are mainly characterized by their `check` and `merge` functions. ::: ::: {#ex-extending-type-check-2 .example} - **Example: Overriding a type check** + ### Overriding a type check ```nix nixThings = mkOption { diff --git a/nixos/doc/manual/development/settings-options.section.md b/nixos/doc/manual/development/settings-options.section.md index 476ba4b03f9d5..5060dd98f58fc 100644 --- a/nixos/doc/manual/development/settings-options.section.md +++ b/nixos/doc/manual/development/settings-options.section.md @@ -143,7 +143,7 @@ These functions all return an attribute set with these values: ::: ::: {#ex-settings-nix-representable .example} -**Example: Module with conventional `settings` option** +### Module with conventional `settings` option The following shows a module for an example program that uses a JSON configuration file. It demonstrates how above values can be used, along @@ -218,7 +218,7 @@ the port, which will enforce it to be a valid integer and make it show up in the manual. ::: {#ex-settings-typed-attrs .example} -**Example: Declaring a type-checked `settings` attribute** +### Declaring a type-checked `settings` attribute ```nix settings = lib.mkOption { type = lib.types.submodule { diff --git a/nixos/doc/manual/development/writing-modules.chapter.md b/nixos/doc/manual/development/writing-modules.chapter.md index ae657458d7680..e07b899e6df7b 100644 --- a/nixos/doc/manual/development/writing-modules.chapter.md +++ b/nixos/doc/manual/development/writing-modules.chapter.md @@ -37,7 +37,7 @@ options, but does not declare any. The structure of full NixOS modules is shown in [Example: Structure of NixOS Modules](#ex-module-syntax). ::: {#ex-module-syntax .example} -**Example: Structure of NixOS Modules** +### Structure of NixOS Modules ```nix { config, pkgs, ... }: @@ -100,7 +100,7 @@ Exec directives](#exec-escaping-example) for an example. When using these functions system environment substitution should *not* be disabled explicitly. ::: {#locate-example .example} -**Example: NixOS Module for the "locate" Service** +### NixOS Module for the "locate" Service ```nix { config, lib, pkgs, ... }: @@ -161,7 +161,7 @@ in { ::: ::: {#exec-escaping-example .example} -**Example: Escaping in Exec directives** +### Escaping in Exec directives ```nix { config, lib, pkgs, utils, ... }: diff --git a/nixos/doc/manual/installation/installing.chapter.md b/nixos/doc/manual/installation/installing.chapter.md index 7d67894e59f92..53cf9ed14c33a 100644 --- a/nixos/doc/manual/installation/installing.chapter.md +++ b/nixos/doc/manual/installation/installing.chapter.md @@ -538,7 +538,7 @@ drive (here `/dev/sda`). [Example: NixOS Configuration](#ex-config) shows a corresponding configuration Nix expression. ::: {#ex-partition-scheme-MBR .example} -**Example: Example partition schemes for NixOS on `/dev/sda` (MBR)** +### Example partition schemes for NixOS on `/dev/sda` (MBR) ```ShellSession # parted /dev/sda -- mklabel msdos # parted /dev/sda -- mkpart primary 1MB -8GB @@ -547,7 +547,7 @@ corresponding configuration Nix expression. ::: ::: {#ex-partition-scheme-UEFI .example} -**Example: Example partition schemes for NixOS on `/dev/sda` (UEFI)** +### Example partition schemes for NixOS on `/dev/sda` (UEFI) ```ShellSession # parted /dev/sda -- mklabel gpt # parted /dev/sda -- mkpart primary 512MB -8GB @@ -558,7 +558,7 @@ corresponding configuration Nix expression. ::: ::: {#ex-install-sequence .example} -**Example: Commands for Installing NixOS on `/dev/sda`** +### Commands for Installing NixOS on `/dev/sda` With a partitioned disk. @@ -578,7 +578,7 @@ With a partitioned disk. ::: ::: {#ex-config .example} -**Example: NixOS Configuration** +### Example: NixOS Configuration ```ShellSession { config, pkgs, ... }: { imports = [ |