Commit 407f6196 authored by pennae's avatar pennae Committed by pennae
Browse files

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.
parent 69259eec

nixos/doc/manual/development/freeform-modules.section.md

+1 −1
Original line number Diff line number Diff line
@@ -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

nixos/doc/manual/development/option-declarations.section.md

+7 −3
Original line number Diff line number Diff line
@@ -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" ]);

nixos/doc/manual/development/option-types.section.md

+9 −9
Original line number Diff line number Diff line
@@ -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 {

nixos/doc/manual/development/settings-options.section.md

+2 −2
Original line number Diff line number Diff line
@@ -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 {

nixos/doc/manual/development/writing-modules.chapter.md

+3 −3
Original line number Diff line number Diff line
@@ -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, ... }: