···

       
13
       
 
       
submodules.

     

       
14
       
 
       


     

       
15
       
 
       
::: {#ex-freeform-module .example}

     

       
16
       
-
       
**Example: Freeform submodule**

     

       
17
       
 
       


     

       
18
       
 
       
The following shows a submodule assigning a freeform type that allows

     

       
19
       
 
       
arbitrary attributes with `str` values below `settings`, but also

     

···

       
13
       
 
       
submodules.

     

       
14
       
 
       


     

       
15
       
 
       
::: {#ex-freeform-module .example}

     

       
16
       
+
       
### Freeform submodule

     

       
17
       
 
       


     

       
18
       
 
       
The following shows a submodule assigning a freeform type that allows

     

       
19
       
 
       
arbitrary attributes with `str` values below `settings`, but also

     

···

       
77
       
 
       
For example:

     

       
78
       
 
       


     

       
79
       
 
       
::: {#ex-options-declarations-util-mkEnableOption-magic .example}

     

       
0
       
 
       

     

       
80
       
 
       
```nix

     

       
81
       
 
       
lib.mkEnableOption (lib.mdDoc "magic")

     

       
82
       
 
       
# is like

     
···

       
126
       
 
       
Examples:

     

       
127
       
 
       


     

       
128
       
 
       
::: {#ex-options-declarations-util-mkPackageOption-hello .example}

     

       
0
       
 
       

     

       
129
       
 
       
```nix

     

       
130
       
 
       
lib.mkPackageOptionMD pkgs "hello" { }

     

       
131
       
 
       
# is like

     
···

       
139
       
 
       
:::

     

       
140
       
 
       


     

       
141
       
 
       
::: {#ex-options-declarations-util-mkPackageOption-ghc .example}

     

       
0
       
 
       

     

       
142
       
 
       
```nix

     

       
143
       
 
       
lib.mkPackageOptionMD pkgs "GHC" {

     

       
144
       
 
       
  default = [ "ghc" ];

     
···

       
156
       
 
       
:::

     

       
157
       
 
       


     

       
158
       
 
       
::: {#ex-options-declarations-util-mkPackageOption-extraDescription .example}

     

       
0
       
 
       

     

       
159
       
 
       
```nix

     

       
160
       
 
       
mkPackageOption pkgs [ "python39Packages" "pytorch" ] {

     

       
161
       
 
       
  extraDescription = "This is an example and doesn't actually do anything.";

     
···

       
217
       
 
       
enforces that there can only be a single display manager enabled.

     

       
218
       
 
       


     

       
219
       
 
       
::: {#ex-option-declaration-eot-service .example}

     

       
220
       
-
       
**Example: Extensible type placeholder in the service module**

     

       
221
       
 
       
```nix

     

       
222
       
 
       
services.xserver.displayManager.enable = mkOption {

     

       
223
       
 
       
  description = "Display manager to use";

     
···

       
227
       
 
       
:::

     

       
228
       
 
       


     

       
229
       
 
       
::: {#ex-option-declaration-eot-backend-gdm .example}

     

       
230
       
-
       
**Example: Extending `services.xserver.displayManager.enable` in the `gdm` module**

     

       
231
       
 
       
```nix

     

       
232
       
 
       
services.xserver.displayManager.enable = mkOption {

     

       
233
       
 
       
  type = with types; nullOr (enum [ "gdm" ]);

     
···

       
236
       
 
       
:::

     

       
237
       
 
       


     

       
238
       
 
       
::: {#ex-option-declaration-eot-backend-sddm .example}

     

       
239
       
-
       
**Example: Extending `services.xserver.displayManager.enable` in the `sddm` module**

     

       
240
       
 
       
```nix

     

       
241
       
 
       
services.xserver.displayManager.enable = mkOption {

     

       
242
       
 
       
  type = with types; nullOr (enum [ "sddm" ]);

     

···

       
77
       
 
       
For example:

     

       
78
       
 
       


     

       
79
       
 
       
::: {#ex-options-declarations-util-mkEnableOption-magic .example}

     

       
80
       
+
       
### `mkEnableOption` usage

     

       
81
       
 
       
```nix

     

       
82
       
 
       
lib.mkEnableOption (lib.mdDoc "magic")

     

       
83
       
 
       
# is like

     
···

       
127
       
 
       
Examples:

     

       
128
       
 
       


     

       
129
       
 
       
::: {#ex-options-declarations-util-mkPackageOption-hello .example}

     

       
130
       
+
       
### Simple `mkPackageOption` usage

     

       
131
       
 
       
```nix

     

       
132
       
 
       
lib.mkPackageOptionMD pkgs "hello" { }

     

       
133
       
 
       
# is like

     
···

       
141
       
 
       
:::

     

       
142
       
 
       


     

       
143
       
 
       
::: {#ex-options-declarations-util-mkPackageOption-ghc .example}

     

       
144
       
+
       
### `mkPackageOption` with explicit default and example

     

       
145
       
 
       
```nix

     

       
146
       
 
       
lib.mkPackageOptionMD pkgs "GHC" {

     

       
147
       
 
       
  default = [ "ghc" ];

     
···

       
159
       
 
       
:::

     

       
160
       
 
       


     

       
161
       
 
       
::: {#ex-options-declarations-util-mkPackageOption-extraDescription .example}

     

       
162
       
+
       
### `mkPackageOption` with additional description text

     

       
163
       
 
       
```nix

     

       
164
       
 
       
mkPackageOption pkgs [ "python39Packages" "pytorch" ] {

     

       
165
       
 
       
  extraDescription = "This is an example and doesn't actually do anything.";

     
···

       
221
       
 
       
enforces that there can only be a single display manager enabled.

     

       
222
       
 
       


     

       
223
       
 
       
::: {#ex-option-declaration-eot-service .example}

     

       
224
       
+
       
### Extensible type placeholder in the service module

     

       
225
       
 
       
```nix

     

       
226
       
 
       
services.xserver.displayManager.enable = mkOption {

     

       
227
       
 
       
  description = "Display manager to use";

     
···

       
231
       
 
       
:::

     

       
232
       
 
       


     

       
233
       
 
       
::: {#ex-option-declaration-eot-backend-gdm .example}

     

       
234
       
+
       
### Extending `services.xserver.displayManager.enable` in the `gdm` module

     

       
235
       
 
       
```nix

     

       
236
       
 
       
services.xserver.displayManager.enable = mkOption {

     

       
237
       
 
       
  type = with types; nullOr (enum [ "gdm" ]);

     
···

       
240
       
 
       
:::

     

       
241
       
 
       


     

       
242
       
 
       
::: {#ex-option-declaration-eot-backend-sddm .example}

     

       
243
       
+
       
### Extending `services.xserver.displayManager.enable` in the `sddm` module

     

       
244
       
 
       
```nix

     

       
245
       
 
       
services.xserver.displayManager.enable = mkOption {

     

       
246
       
 
       
  type = with types; nullOr (enum [ "sddm" ]);

     

···

       
36
       
 
       
    together. This type is recommended when the option type is unknown.

     

       
37
       
 
       


     

       
38
       
 
       
    ::: {#ex-types-anything .example}

     

       
39
       
-
       
    **Example: `types.anything` Example**

     

       
40
       
 
       


     

       
41
       
 
       
    Two definitions of this type like

     

       
42
       
 
       


     
···

       
356
       
 
       
if you want to allow users to leave it undefined.

     

       
357
       
 
       


     

       
358
       
 
       
::: {#ex-submodule-direct .example}

     

       
359
       
-
       
**Example: Directly defined submodule**

     

       
360
       
 
       
```nix

     

       
361
       
 
       
options.mod = mkOption {

     

       
362
       
 
       
  description = "submodule example";

     
···

       
375
       
 
       
:::

     

       
376
       
 
       


     

       
377
       
 
       
::: {#ex-submodule-reference .example}

     

       
378
       
-
       
**Example: Submodule defined as a reference**

     

       
379
       
 
       
```nix

     

       
380
       
 
       
let

     

       
381
       
 
       
  modOptions = {

     
···

       
403
       
 
       
([Example: Definition of a list of submodules](#ex-submodule-listof-definition)).

     

       
404
       
 
       


     

       
405
       
 
       
::: {#ex-submodule-listof-declaration .example}

     

       
406
       
-
       
**Example: Declaration of a list of submodules**

     

       
407
       
 
       
```nix

     

       
408
       
 
       
options.mod = mkOption {

     

       
409
       
 
       
  description = "submodule example";

     
···

       
422
       
 
       
:::

     

       
423
       
 
       


     

       
424
       
 
       
::: {#ex-submodule-listof-definition .example}

     

       
425
       
-
       
**Example: Definition of a list of submodules**

     

       
426
       
 
       
```nix

     

       
427
       
 
       
config.mod = [

     

       
428
       
 
       
  { foo = 1; bar = "one"; }

     
···

       
437
       
 
       
([Example: Definition of attribute sets of submodules](#ex-submodule-attrsof-definition)).

     

       
438
       
 
       


     

       
439
       
 
       
::: {#ex-submodule-attrsof-declaration .example}

     

       
440
       
-
       
**Example: Declaration of attribute sets of submodules**

     

       
441
       
 
       
```nix

     

       
442
       
 
       
options.mod = mkOption {

     

       
443
       
 
       
  description = "submodule example";

     
···

       
456
       
 
       
:::

     

       
457
       
 
       


     

       
458
       
 
       
::: {#ex-submodule-attrsof-definition .example}

     

       
459
       
-
       
**Example: Definition of attribute sets of submodules**

     

       
460
       
 
       
```nix

     

       
461
       
 
       
config.mod.one = { foo = 1; bar = "one"; };

     

       
462
       
 
       
config.mod.two = { foo = 2; bar = "two"; };

     
···

       
476
       
 
       
    ([Example: Overriding a type check](#ex-extending-type-check-2)).

     

       
477
       
 
       


     

       
478
       
 
       
    ::: {#ex-extending-type-check-1 .example}

     

       
479
       
-
       
    **Example: Adding a type check**

     

       
480
       
 
       


     

       
481
       
 
       
    ```nix

     

       
482
       
 
       
    byte = mkOption {

     
···

       
487
       
 
       
    :::

     

       
488
       
 
       


     

       
489
       
 
       
    ::: {#ex-extending-type-check-2 .example}

     

       
490
       
-
       
    **Example: Overriding a type check**

     

       
491
       
 
       


     

       
492
       
 
       
    ```nix

     

       
493
       
 
       
    nixThings = mkOption {

     

···

       
36
       
 
       
    together. This type is recommended when the option type is unknown.

     

       
37
       
 
       


     

       
38
       
 
       
    ::: {#ex-types-anything .example}

     

       
39
       
+
       
    ### `types.anything`

     

       
40
       
 
       


     

       
41
       
 
       
    Two definitions of this type like

     

       
42
       
 
       


     
···

       
356
       
 
       
if you want to allow users to leave it undefined.

     

       
357
       
 
       


     

       
358
       
 
       
::: {#ex-submodule-direct .example}

     

       
359
       
+
       
### Directly defined submodule

     

       
360
       
 
       
```nix

     

       
361
       
 
       
options.mod = mkOption {

     

       
362
       
 
       
  description = "submodule example";

     
···

       
375
       
 
       
:::

     

       
376
       
 
       


     

       
377
       
 
       
::: {#ex-submodule-reference .example}

     

       
378
       
+
       
### Submodule defined as a reference

     

       
379
       
 
       
```nix

     

       
380
       
 
       
let

     

       
381
       
 
       
  modOptions = {

     
···

       
403
       
 
       
([Example: Definition of a list of submodules](#ex-submodule-listof-definition)).

     

       
404
       
 
       


     

       
405
       
 
       
::: {#ex-submodule-listof-declaration .example}

     

       
406
       
+
       
### Declaration of a list of submodules

     

       
407
       
 
       
```nix

     

       
408
       
 
       
options.mod = mkOption {

     

       
409
       
 
       
  description = "submodule example";

     
···

       
422
       
 
       
:::

     

       
423
       
 
       


     

       
424
       
 
       
::: {#ex-submodule-listof-definition .example}

     

       
425
       
+
       
### Definition of a list of submodules

     

       
426
       
 
       
```nix

     

       
427
       
 
       
config.mod = [

     

       
428
       
 
       
  { foo = 1; bar = "one"; }

     
···

       
437
       
 
       
([Example: Definition of attribute sets of submodules](#ex-submodule-attrsof-definition)).

     

       
438
       
 
       


     

       
439
       
 
       
::: {#ex-submodule-attrsof-declaration .example}

     

       
440
       
+
       
### Declaration of attribute sets of submodules

     

       
441
       
 
       
```nix

     

       
442
       
 
       
options.mod = mkOption {

     

       
443
       
 
       
  description = "submodule example";

     
···

       
456
       
 
       
:::

     

       
457
       
 
       


     

       
458
       
 
       
::: {#ex-submodule-attrsof-definition .example}

     

       
459
       
+
       
### Definition of attribute sets of submodules

     

       
460
       
 
       
```nix

     

       
461
       
 
       
config.mod.one = { foo = 1; bar = "one"; };

     

       
462
       
 
       
config.mod.two = { foo = 2; bar = "two"; };

     
···

       
476
       
 
       
    ([Example: Overriding a type check](#ex-extending-type-check-2)).

     

       
477
       
 
       


     

       
478
       
 
       
    ::: {#ex-extending-type-check-1 .example}

     

       
479
       
+
       
    ### Adding a type check

     

       
480
       
 
       


     

       
481
       
 
       
    ```nix

     

       
482
       
 
       
    byte = mkOption {

     
···

       
487
       
 
       
    :::

     

       
488
       
 
       


     

       
489
       
 
       
    ::: {#ex-extending-type-check-2 .example}

     

       
490
       
+
       
    ### Overriding a type check

     

       
491
       
 
       


     

       
492
       
 
       
    ```nix

     

       
493
       
 
       
    nixThings = mkOption {

     

···

       
143
       
 
       
    :::

     

       
144
       
 
       


     

       
145
       
 
       
::: {#ex-settings-nix-representable .example}

     

       
146
       
-
       
**Example: Module with conventional `settings` option**

     

       
147
       
 
       


     

       
148
       
 
       
The following shows a module for an example program that uses a JSON

     

       
149
       
 
       
configuration file. It demonstrates how above values can be used, along

     
···

       
218
       
 
       
up in the manual.

     

       
219
       
 
       


     

       
220
       
 
       
::: {#ex-settings-typed-attrs .example}

     

       
221
       
-
       
**Example: Declaring a type-checked `settings` attribute**

     

       
222
       
 
       
```nix

     

       
223
       
 
       
settings = lib.mkOption {

     

       
224
       
 
       
  type = lib.types.submodule {

     

···

       
143
       
 
       
    :::

     

       
144
       
 
       


     

       
145
       
 
       
::: {#ex-settings-nix-representable .example}

     

       
146
       
+
       
### Module with conventional `settings` option

     

       
147
       
 
       


     

       
148
       
 
       
The following shows a module for an example program that uses a JSON

     

       
149
       
 
       
configuration file. It demonstrates how above values can be used, along

     
···

       
218
       
 
       
up in the manual.

     

       
219
       
 
       


     

       
220
       
 
       
::: {#ex-settings-typed-attrs .example}

     

       
221
       
+
       
### Declaring a type-checked `settings` attribute

     

       
222
       
 
       
```nix

     

       
223
       
 
       
settings = lib.mkOption {

     

       
224
       
 
       
  type = lib.types.submodule {

     

···

       
37
       
 
       
is shown in [Example: Structure of NixOS Modules](#ex-module-syntax).

     

       
38
       
 
       


     

       
39
       
 
       
::: {#ex-module-syntax .example}

     

       
40
       
-
       
**Example: Structure of NixOS Modules**

     

       
41
       
 
       
```nix

     

       
42
       
 
       
{ config, pkgs, ... }:

     

       
43
       
 
       


     
···

       
100
       
 
       
functions system environment substitution should *not* be disabled explicitly.

     

       
101
       
 
       


     

       
102
       
 
       
::: {#locate-example .example}

     

       
103
       
-
       
**Example: NixOS Module for the "locate" Service**

     

       
104
       
 
       
```nix

     

       
105
       
 
       
{ config, lib, pkgs, ... }:

     

       
106
       
 
       


     
···

       
161
       
 
       
:::

     

       
162
       
 
       


     

       
163
       
 
       
::: {#exec-escaping-example .example}

     

       
164
       
-
       
**Example: Escaping in Exec directives**

     

       
165
       
 
       
```nix

     

       
166
       
 
       
{ config, lib, pkgs, utils, ... }:

     

       
167
       
 
       


     

···

       
37
       
 
       
is shown in [Example: Structure of NixOS Modules](#ex-module-syntax).

     

       
38
       
 
       


     

       
39
       
 
       
::: {#ex-module-syntax .example}

     

       
40
       
+
       
### Structure of NixOS Modules

     

       
41
       
 
       
```nix

     

       
42
       
 
       
{ config, pkgs, ... }:

     

       
43
       
 
       


     
···

       
100
       
 
       
functions system environment substitution should *not* be disabled explicitly.

     

       
101
       
 
       


     

       
102
       
 
       
::: {#locate-example .example}

     

       
103
       
+
       
### NixOS Module for the "locate" Service

     

       
104
       
 
       
```nix

     

       
105
       
 
       
{ config, lib, pkgs, ... }:

     

       
106
       
 
       


     
···

       
161
       
 
       
:::

     

       
162
       
 
       


     

       
163
       
 
       
::: {#exec-escaping-example .example}

     

       
164
       
+
       
### Escaping in Exec directives

     

       
165
       
 
       
```nix

     

       
166
       
 
       
{ config, lib, pkgs, utils, ... }:

     

       
167
       
 
       


     

···

       
538
       
 
       
corresponding configuration Nix expression.

     

       
539
       
 
       


     

       
540
       
 
       
::: {#ex-partition-scheme-MBR .example}

     

       
541
       
-
       
**Example: Example partition schemes for NixOS on `/dev/sda` (MBR)**

     

       
542
       
 
       
```ShellSession

     

       
543
       
 
       
# parted /dev/sda -- mklabel msdos

     

       
544
       
 
       
# parted /dev/sda -- mkpart primary 1MB -8GB

     
···

       
547
       
 
       
:::

     

       
548
       
 
       


     

       
549
       
 
       
::: {#ex-partition-scheme-UEFI .example}

     

       
550
       
-
       
**Example: Example partition schemes for NixOS on `/dev/sda` (UEFI)**

     

       
551
       
 
       
```ShellSession

     

       
552
       
 
       
# parted /dev/sda -- mklabel gpt

     

       
553
       
 
       
# parted /dev/sda -- mkpart primary 512MB -8GB

     
···

       
558
       
 
       
:::

     

       
559
       
 
       


     

       
560
       
 
       
::: {#ex-install-sequence .example}

     

       
561
       
-
       
**Example: Commands for Installing NixOS on `/dev/sda`**

     

       
562
       
 
       


     

       
563
       
 
       
With a partitioned disk.

     

       
564
       
 
       


     
···

       
578
       
 
       
:::

     

       
579
       
 
       


     

       
580
       
 
       
::: {#ex-config .example}

     

       
581
       
-
       
**Example: NixOS Configuration**

     

       
582
       
 
       
```ShellSession

     

       
583
       
 
       
{ config, pkgs, ... }: {

     

       
584
       
 
       
  imports = [

     

···

       
538
       
 
       
corresponding configuration Nix expression.

     

       
539
       
 
       


     

       
540
       
 
       
::: {#ex-partition-scheme-MBR .example}

     

       
541
       
+
       
### Example partition schemes for NixOS on `/dev/sda` (MBR)

     

       
542
       
 
       
```ShellSession

     

       
543
       
 
       
# parted /dev/sda -- mklabel msdos

     

       
544
       
 
       
# parted /dev/sda -- mkpart primary 1MB -8GB

     
···

       
547
       
 
       
:::

     

       
548
       
 
       


     

       
549
       
 
       
::: {#ex-partition-scheme-UEFI .example}

     

       
550
       
+
       
### Example partition schemes for NixOS on `/dev/sda` (UEFI)

     

       
551
       
 
       
```ShellSession

     

       
552
       
 
       
# parted /dev/sda -- mklabel gpt

     

       
553
       
 
       
# parted /dev/sda -- mkpart primary 512MB -8GB

     
···

       
558
       
 
       
:::

     

       
559
       
 
       


     

       
560
       
 
       
::: {#ex-install-sequence .example}

     

       
561
       
+
       
### Commands for Installing NixOS on `/dev/sda`

     

       
562
       
 
       


     

       
563
       
 
       
With a partitioned disk.

     

       
564
       
 
       


     
···

       
578
       
 
       
:::

     

       
579
       
 
       


     

       
580
       
 
       
::: {#ex-config .example}

     

       
581
       
+
       
### Example: NixOS Configuration

     

       
582
       
 
       
```ShellSession

     

       
583
       
 
       
{ config, pkgs, ... }: {

     

       
584
       
 
       
  imports = [

     

···

       
218
       
 
       
            result += f"<partintro{maybe_id}>"

     

       
219
       
 
       
        return result

     

       
220
       
 
       
    def example_open(self, token: Token, tokens: Sequence[Token], i: int) -> str:

     

       
221
       
-
       
        if id := token.attrs.get('id'):

     

       
222
       
-
       
            return f"<anchor xml:id={quoteattr(cast(str, id))} />"

     

       
223
       
-
       
        return ""

     

       
224
       
 
       
    def example_close(self, token: Token, tokens: Sequence[Token], i: int) -> str:

     

       
225
       
-
       
        return ""

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
226
       
 
       


     

       
227
       
 
       
    def _close_headings(self, level: Optional[int]) -> str:

     

       
228
       
 
       
        # we rely on markdown-it producing h{1..6} tags in token.tag for this to work

     

···

       
218
       
 
       
            result += f"<partintro{maybe_id}>"

     

       
219
       
 
       
        return result

     

       
220
       
 
       
    def example_open(self, token: Token, tokens: Sequence[Token], i: int) -> str:

     

       
221
       
+
       
        if id := cast(str, token.attrs.get('id', '')):

     

       
222
       
+
       
            id = f'xml:id={quoteattr(id)}' if id else ''

     

       
223
       
+
       
        return f'<example {id}>'

     

       
224
       
 
       
    def example_close(self, token: Token, tokens: Sequence[Token], i: int) -> str:

     

       
225
       
+
       
        return "</example>"

     

       
226
       
+
       
    def example_title_open(self, token: Token, tokens: Sequence[Token], i: int) -> str:

     

       
227
       
+
       
        return "<title>"

     

       
228
       
+
       
    def example_title_close(self, token: Token, tokens: Sequence[Token], i: int) -> str:

     

       
229
       
+
       
        return "</title>"

     

       
230
       
 
       


     

       
231
       
 
       
    def _close_headings(self, level: Optional[int]) -> str:

     

       
232
       
 
       
        # we rely on markdown-it producing h{1..6} tags in token.tag for this to work

     

···

       
214
       
 
       
        self._ordered_list_nesting -= 1;

     

       
215
       
 
       
        return "</ol></div>"

     

       
216
       
 
       
    def example_open(self, token: Token, tokens: Sequence[Token], i: int) -> str:

     

       
217
       
-
       
        if id := token.attrs.get('id'):

     

       
218
       
-
       
            return f'<a id="{escape(cast(str, id), True)}" />'

     

       
219
       
-
       
        return ""

     

       
220
       
 
       
    def example_close(self, token: Token, tokens: Sequence[Token], i: int) -> str:

     

       
221
       
-
       
        return ""

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
222
       
 
       


     

       
223
       
 
       
    def _make_hN(self, level: int) -> tuple[str, str]:

     

       
224
       
 
       
        return f"h{min(6, max(1, level + self._hlevel_offset))}", ""

     

···

       
214
       
 
       
        self._ordered_list_nesting -= 1;

     

       
215
       
 
       
        return "</ol></div>"

     

       
216
       
 
       
    def example_open(self, token: Token, tokens: Sequence[Token], i: int) -> str:

     

       
217
       
+
       
        if id := cast(str, token.attrs.get('id', '')):

     

       
218
       
+
       
            id = f'id="{escape(id, True)}"' if id else ''

     

       
219
       
+
       
        return f'<div class="example"><a {id} />'

     

       
220
       
 
       
    def example_close(self, token: Token, tokens: Sequence[Token], i: int) -> str:

     

       
221
       
+
       
        return '</div></div><br class="example-break" />'

     

       
222
       
+
       
    def example_title_open(self, token: Token, tokens: Sequence[Token], i: int) -> str:

     

       
223
       
+
       
        return '<p class="title"><strong>'

     

       
224
       
+
       
    def example_title_close(self, token: Token, tokens: Sequence[Token], i: int) -> str:

     

       
225
       
+
       
        return '</strong></p><div class="example-contents">'

     

       
226
       
 
       


     

       
227
       
 
       
    def _make_hN(self, level: int) -> tuple[str, str]:

     

       
228
       
 
       
        return f"h{min(6, max(1, level + self._hlevel_offset))}", ""

     

···

       
402
       
 
       
        )

     

       
403
       
 
       
        if not (items := walk_and_emit(toc, toc_depth)):

     

       
404
       
 
       
            return ""

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
405
       
 
       
        return (

     

       
406
       
 
       
            f'<div class="toc">'

     

       
407
       
 
       
            f' <p><strong>Table of Contents</strong></p>'

     
···

       
409
       
 
       
            f'  {"".join(items)}'

     

       
410
       
 
       
            f' </dl>'

     

       
411
       
 
       
            f'</div>'

     

       
0
       
 
       

     

       
412
       
 
       
        )

     

       
413
       
 
       


     

       
414
       
 
       
    def _make_hN(self, level: int) -> tuple[str, str]:

     
···

       
513
       
 
       
            self._redirection_targets.add(into)

     

       
514
       
 
       
        return tokens

     

       
515
       
 
       


     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
516
       
 
       
    # xref | (id, type, heading inlines, file, starts new file)

     

       
517
       
 
       
    def _collect_ids(self, tokens: Sequence[Token], target_file: str, typ: str, file_changed: bool

     

       
518
       
 
       
                     ) -> list[XrefTarget | tuple[str, str, Token, str, bool]]:

     
···

       
534
       
 
       
                subtyp = bt.type.removeprefix('included_').removesuffix('s')

     

       
535
       
 
       
                for si, (sub, _path) in enumerate(bt.meta['included']):

     

       
536
       
 
       
                    result += self._collect_ids(sub, sub_file, subtyp, si == 0 and sub_file != target_file)

     

       
0
       
 
       

     

       
0
       
 
       

     

       
537
       
 
       
            elif bt.type == 'inline':

     

       
538
       
 
       
                assert bt.children

     

       
539
       
 
       
                result += self._collect_ids(bt.children, target_file, typ, False)

     
···

       
558
       
 
       
            title = prefix + title_html

     

       
559
       
 
       
            toc_html = f"{n}. {title_html}"

     

       
560
       
 
       
            title_html = f"Appendix&nbsp;{n}"

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
561
       
 
       
        else:

     

       
562
       
 
       
            toc_html, title = title_html, title_html

     

       
563
       
 
       
            title_html = (

     
···

       
569
       
 
       
        return XrefTarget(id, title_html, toc_html, re.sub('<.*?>', '', title), path, drop_fragment)

     

       
570
       
 
       


     

       
571
       
 
       
    def _postprocess(self, infile: Path, outfile: Path, tokens: Sequence[Token]) -> None:

     

       
0
       
 
       

     

       
572
       
 
       
        xref_queue = self._collect_ids(tokens, outfile.name, 'book', True)

     

       
573
       
 
       


     

       
574
       
 
       
        failed = False

     

···

       
402
       
 
       
        )

     

       
403
       
 
       
        if not (items := walk_and_emit(toc, toc_depth)):

     

       
404
       
 
       
            return ""

     

       
405
       
+
       
        examples = ""

     

       
406
       
+
       
        if toc.examples:

     

       
407
       
+
       
            examples_entries = [

     

       
408
       
+
       
                f'<dt>{i + 1}. <a href="{ex.target.href()}">{ex.target.toc_html}</a></dt>'

     

       
409
       
+
       
                for i, ex in enumerate(toc.examples)

     

       
410
       
+
       
            ]

     

       
411
       
+
       
            examples = (

     

       
412
       
+
       
                '<div class="list-of-examples">'

     

       
413
       
+
       
                '<p><strong>List of Examples</strong><p>'

     

       
414
       
+
       
                f'<dl>{"".join(examples_entries)}</dl>'

     

       
415
       
+
       
                '</div>'

     

       
416
       
+
       
            )

     

       
417
       
 
       
        return (

     

       
418
       
 
       
            f'<div class="toc">'

     

       
419
       
 
       
            f' <p><strong>Table of Contents</strong></p>'

     
···

       
421
       
 
       
            f'  {"".join(items)}'

     

       
422
       
 
       
            f' </dl>'

     

       
423
       
 
       
            f'</div>'

     

       
424
       
+
       
            f'{examples}'

     

       
425
       
 
       
        )

     

       
426
       
 
       


     

       
427
       
 
       
    def _make_hN(self, level: int) -> tuple[str, str]:

     
···

       
526
       
 
       
            self._redirection_targets.add(into)

     

       
527
       
 
       
        return tokens

     

       
528
       
 
       


     

       
529
       
+
       
    def _number_examples(self, tokens: Sequence[Token], start: int = 1) -> int:

     

       
530
       
+
       
        for (i, token) in enumerate(tokens):

     

       
531
       
+
       
            if token.type == "example_title_open":

     

       
532
       
+
       
                title = tokens[i + 1]

     

       
533
       
+
       
                assert title.type == 'inline' and title.children

     

       
534
       
+
       
                # the prefix is split into two tokens because the xref title_html will want

     

       
535
       
+
       
                # only the first of the two, but both must be rendered into the example itself.

     

       
536
       
+
       
                title.children = (

     

       
537
       
+
       
                    [

     

       
538
       
+
       
                        Token('text', '', 0, content=f'Example {start}'),

     

       
539
       
+
       
                        Token('text', '', 0, content='. ')

     

       
540
       
+
       
                    ] + title.children

     

       
541
       
+
       
                )

     

       
542
       
+
       
                start += 1

     

       
543
       
+
       
            elif token.type.startswith('included_') and token.type != 'included_options':

     

       
544
       
+
       
                for sub, _path in token.meta['included']:

     

       
545
       
+
       
                    start = self._number_examples(sub, start)

     

       
546
       
+
       
        return start

     

       
547
       
+
       


     

       
548
       
 
       
    # xref | (id, type, heading inlines, file, starts new file)

     

       
549
       
 
       
    def _collect_ids(self, tokens: Sequence[Token], target_file: str, typ: str, file_changed: bool

     

       
550
       
 
       
                     ) -> list[XrefTarget | tuple[str, str, Token, str, bool]]:

     
···

       
566
       
 
       
                subtyp = bt.type.removeprefix('included_').removesuffix('s')

     

       
567
       
 
       
                for si, (sub, _path) in enumerate(bt.meta['included']):

     

       
568
       
 
       
                    result += self._collect_ids(sub, sub_file, subtyp, si == 0 and sub_file != target_file)

     

       
569
       
+
       
            elif bt.type == 'example_open' and (id := cast(str, bt.attrs.get('id', ''))):

     

       
570
       
+
       
                result.append((id, 'example', tokens[i + 2], target_file, False))

     

       
571
       
 
       
            elif bt.type == 'inline':

     

       
572
       
 
       
                assert bt.children

     

       
573
       
 
       
                result += self._collect_ids(bt.children, target_file, typ, False)

     
···

       
592
       
 
       
            title = prefix + title_html

     

       
593
       
 
       
            toc_html = f"{n}. {title_html}"

     

       
594
       
 
       
            title_html = f"Appendix&nbsp;{n}"

     

       
595
       
+
       
        elif typ == 'example':

     

       
596
       
+
       
            # skip the prepended `Example N. ` from _number_examples

     

       
597
       
+
       
            toc_html, title = self._renderer.renderInline(inlines.children[2:]), title_html

     

       
598
       
+
       
            # xref title wants only the prepended text, sans the trailing colon and space

     

       
599
       
+
       
            title_html = self._renderer.renderInline(inlines.children[0:1])

     

       
600
       
 
       
        else:

     

       
601
       
 
       
            toc_html, title = title_html, title_html

     

       
602
       
 
       
            title_html = (

     
···

       
608
       
 
       
        return XrefTarget(id, title_html, toc_html, re.sub('<.*?>', '', title), path, drop_fragment)

     

       
609
       
 
       


     

       
610
       
 
       
    def _postprocess(self, infile: Path, outfile: Path, tokens: Sequence[Token]) -> None:

     

       
611
       
+
       
        self._number_examples(tokens)

     

       
612
       
 
       
        xref_queue = self._collect_ids(tokens, outfile.name, 'book', True)

     

       
613
       
 
       


     

       
614
       
 
       
        failed = False

     

···

       
14
       
 
       
FragmentType = Literal['preface', 'part', 'chapter', 'section', 'appendix']

     

       
15
       
 
       


     

       
16
       
 
       
# in the TOC all fragments are allowed, plus the all-encompassing book.

     

       
17
       
-
       
TocEntryType = Literal['book', 'preface', 'part', 'chapter', 'section', 'appendix']

     

       
18
       
 
       


     

       
19
       
 
       
def is_include(token: Token) -> bool:

     

       
20
       
 
       
    return token.type == "fence" and token.info.startswith("{=include=} ")

     
···

       
124
       
 
       
    next: TocEntry | None = None

     

       
125
       
 
       
    children: list[TocEntry] = dc.field(default_factory=list)

     

       
126
       
 
       
    starts_new_chunk: bool = False

     

       
0
       
 
       

     

       
127
       
 
       


     

       
128
       
 
       
    @property

     

       
129
       
 
       
    def root(self) -> TocEntry:

     
···

       
138
       
 
       


     

       
139
       
 
       
    @classmethod

     

       
140
       
 
       
    def collect_and_link(cls, xrefs: dict[str, XrefTarget], tokens: Sequence[Token]) -> TocEntry:

     

       
141
       
-
       
        result = cls._collect_entries(xrefs, tokens, 'book')

     

       
142
       
 
       


     

       
143
       
 
       
        def flatten_with_parent(this: TocEntry, parent: TocEntry | None) -> Iterable[TocEntry]:

     

       
144
       
 
       
            this.parent = parent

     

       
145
       
 
       
            return itertools.chain([this], *[ flatten_with_parent(c, this) for c in this.children ])

     

       
146
       
 
       


     

       
147
       
-
       
        flat = list(flatten_with_parent(result, None))

     

       
148
       
 
       
        prev = flat[0]

     

       
149
       
 
       
        prev.starts_new_chunk = True

     

       
150
       
 
       
        paths_seen = set([prev.target.path])

     
···

       
155
       
 
       
                prev = c

     

       
156
       
 
       
            paths_seen.add(c.target.path)

     

       
157
       
 
       


     

       
0
       
 
       

     

       
0
       
 
       

     

       
158
       
 
       
        for c in flat:

     

       
159
       
 
       
            c.freeze()

     

       
160
       
 
       


     

       
161
       
-
       
        return result

     

       
162
       
 
       


     

       
163
       
 
       
    @classmethod

     

       
164
       
 
       
    def _collect_entries(cls, xrefs: dict[str, XrefTarget], tokens: Sequence[Token],

     

       
165
       
-
       
                         kind: TocEntryType) -> TocEntry:

     

       
166
       
 
       
        # we assume that check_structure has been run recursively over the entire input.

     

       
167
       
 
       
        # list contains (tag, entry) pairs that will collapse to a single entry for

     

       
168
       
 
       
        # the full sequence.

     

       
169
       
 
       
        entries: list[tuple[str, TocEntry]] = []

     

       
0
       
 
       

     

       
170
       
 
       
        for token in tokens:

     

       
171
       
 
       
            if token.type.startswith('included_') and (included := token.meta.get('included')):

     

       
172
       
 
       
                fragment_type_str = token.type[9:].removesuffix('s')

     

       
173
       
 
       
                assert fragment_type_str in get_args(TocEntryType)

     

       
174
       
 
       
                fragment_type = cast(TocEntryType, fragment_type_str)

     

       
175
       
 
       
                for fragment, _path in included:

     

       
176
       
-
       
                    entries[-1][1].children.append(cls._collect_entries(xrefs, fragment, fragment_type))

     

       
0
       
 
       

     

       
0
       
 
       

     

       
177
       
 
       
            elif token.type == 'heading_open' and (id := cast(str, token.attrs.get('id', ''))):

     

       
178
       
 
       
                while len(entries) > 1 and entries[-1][0] >= token.tag:

     

       
179
       
 
       
                    entries[-2][1].children.append(entries.pop()[1])

     

       
180
       
 
       
                entries.append((token.tag,

     

       
181
       
 
       
                                TocEntry(kind if token.tag == 'h1' else 'section', xrefs[id])))

     

       
182
       
 
       
                token.meta['TocEntry'] = entries[-1][1]

     

       
0
       
 
       

     

       
0
       
 
       

     

       
183
       
 
       


     

       
184
       
 
       
        while len(entries) > 1:

     

       
185
       
 
       
            entries[-2][1].children.append(entries.pop()[1])

     

       
186
       
-
       
        return entries[0][1]

     

···

       
14
       
 
       
FragmentType = Literal['preface', 'part', 'chapter', 'section', 'appendix']

     

       
15
       
 
       


     

       
16
       
 
       
# in the TOC all fragments are allowed, plus the all-encompassing book.

     

       
17
       
+
       
TocEntryType = Literal['book', 'preface', 'part', 'chapter', 'section', 'appendix', 'example']

     

       
18
       
 
       


     

       
19
       
 
       
def is_include(token: Token) -> bool:

     

       
20
       
 
       
    return token.type == "fence" and token.info.startswith("{=include=} ")

     
···

       
124
       
 
       
    next: TocEntry | None = None

     

       
125
       
 
       
    children: list[TocEntry] = dc.field(default_factory=list)

     

       
126
       
 
       
    starts_new_chunk: bool = False

     

       
127
       
+
       
    examples: list[TocEntry] = dc.field(default_factory=list)

     

       
128
       
 
       


     

       
129
       
 
       
    @property

     

       
130
       
 
       
    def root(self) -> TocEntry:

     
···

       
139
       
 
       


     

       
140
       
 
       
    @classmethod

     

       
141
       
 
       
    def collect_and_link(cls, xrefs: dict[str, XrefTarget], tokens: Sequence[Token]) -> TocEntry:

     

       
142
       
+
       
        entries, examples = cls._collect_entries(xrefs, tokens, 'book')

     

       
143
       
 
       


     

       
144
       
 
       
        def flatten_with_parent(this: TocEntry, parent: TocEntry | None) -> Iterable[TocEntry]:

     

       
145
       
 
       
            this.parent = parent

     

       
146
       
 
       
            return itertools.chain([this], *[ flatten_with_parent(c, this) for c in this.children ])

     

       
147
       
 
       


     

       
148
       
+
       
        flat = list(flatten_with_parent(entries, None))

     

       
149
       
 
       
        prev = flat[0]

     

       
150
       
 
       
        prev.starts_new_chunk = True

     

       
151
       
 
       
        paths_seen = set([prev.target.path])

     
···

       
156
       
 
       
                prev = c

     

       
157
       
 
       
            paths_seen.add(c.target.path)

     

       
158
       
 
       


     

       
159
       
+
       
        flat[0].examples = examples

     

       
160
       
+
       


     

       
161
       
 
       
        for c in flat:

     

       
162
       
 
       
            c.freeze()

     

       
163
       
 
       


     

       
164
       
+
       
        return entries

     

       
165
       
 
       


     

       
166
       
 
       
    @classmethod

     

       
167
       
 
       
    def _collect_entries(cls, xrefs: dict[str, XrefTarget], tokens: Sequence[Token],

     

       
168
       
+
       
                         kind: TocEntryType) -> tuple[TocEntry, list[TocEntry]]:

     

       
169
       
 
       
        # we assume that check_structure has been run recursively over the entire input.

     

       
170
       
 
       
        # list contains (tag, entry) pairs that will collapse to a single entry for

     

       
171
       
 
       
        # the full sequence.

     

       
172
       
 
       
        entries: list[tuple[str, TocEntry]] = []

     

       
173
       
+
       
        examples: list[TocEntry] = []

     

       
174
       
 
       
        for token in tokens:

     

       
175
       
 
       
            if token.type.startswith('included_') and (included := token.meta.get('included')):

     

       
176
       
 
       
                fragment_type_str = token.type[9:].removesuffix('s')

     

       
177
       
 
       
                assert fragment_type_str in get_args(TocEntryType)

     

       
178
       
 
       
                fragment_type = cast(TocEntryType, fragment_type_str)

     

       
179
       
 
       
                for fragment, _path in included:

     

       
180
       
+
       
                    subentries, subexamples = cls._collect_entries(xrefs, fragment, fragment_type)

     

       
181
       
+
       
                    entries[-1][1].children.append(subentries)

     

       
182
       
+
       
                    examples += subexamples

     

       
183
       
 
       
            elif token.type == 'heading_open' and (id := cast(str, token.attrs.get('id', ''))):

     

       
184
       
 
       
                while len(entries) > 1 and entries[-1][0] >= token.tag:

     

       
185
       
 
       
                    entries[-2][1].children.append(entries.pop()[1])

     

       
186
       
 
       
                entries.append((token.tag,

     

       
187
       
 
       
                                TocEntry(kind if token.tag == 'h1' else 'section', xrefs[id])))

     

       
188
       
 
       
                token.meta['TocEntry'] = entries[-1][1]

     

       
189
       
+
       
            elif token.type == 'example_open' and (id := cast(str, token.attrs.get('id', ''))):

     

       
190
       
+
       
                examples.append(TocEntry('example', xrefs[id]))

     

       
191
       
 
       


     

       
192
       
 
       
        while len(entries) > 1:

     

       
193
       
 
       
            entries[-2][1].children.append(entries.pop()[1])

     

       
194
       
+
       
        return (entries[0][1], examples)

     

···

       
88
       
 
       
            "ordered_list_close": self.ordered_list_close,

     

       
89
       
 
       
            "example_open": self.example_open,

     

       
90
       
 
       
            "example_close": self.example_close,

     

       
0
       
 
       

     

       
0
       
 
       

     

       
91
       
 
       
        }

     

       
92
       
 
       


     

       
93
       
 
       
        self._admonitions = {

     
···

       
218
       
 
       
    def example_open(self, token: Token, tokens: Sequence[Token], i: int) -> str:

     

       
219
       
 
       
        raise RuntimeError("md token not supported", token)

     

       
220
       
 
       
    def example_close(self, token: Token, tokens: Sequence[Token], i: int) -> str:

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
221
       
 
       
        raise RuntimeError("md token not supported", token)

     

       
222
       
 
       


     

       
223
       
 
       
def _is_escaped(src: str, pos: int) -> bool:

     
···

       
417
       
 
       


     

       
418
       
 
       
    md.core.ruler.push("block_attr", block_attr)

     

       
419
       
 
       


     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
420
       
 
       
TR = TypeVar('TR', bound='Renderer')

     

       
421
       
 
       


     

       
422
       
 
       
class Converter(ABC, Generic[TR]):

     
···

       
459
       
 
       
        self._md.use(_heading_ids)

     

       
460
       
 
       
        self._md.use(_compact_list_attr)

     

       
461
       
 
       
        self._md.use(_block_attr)

     

       
0
       
 
       

     

       
462
       
 
       
        self._md.enable(["smartquotes", "replacements"])

     

       
463
       
 
       


     

       
464
       
 
       
    def _parse(self, src: str) -> list[Token]:

     

···

       
88
       
 
       
            "ordered_list_close": self.ordered_list_close,

     

       
89
       
 
       
            "example_open": self.example_open,

     

       
90
       
 
       
            "example_close": self.example_close,

     

       
91
       
+
       
            "example_title_open": self.example_title_open,

     

       
92
       
+
       
            "example_title_close": self.example_title_close,

     

       
93
       
 
       
        }

     

       
94
       
 
       


     

       
95
       
 
       
        self._admonitions = {

     
···

       
220
       
 
       
    def example_open(self, token: Token, tokens: Sequence[Token], i: int) -> str:

     

       
221
       
 
       
        raise RuntimeError("md token not supported", token)

     

       
222
       
 
       
    def example_close(self, token: Token, tokens: Sequence[Token], i: int) -> str:

     

       
223
       
+
       
        raise RuntimeError("md token not supported", token)

     

       
224
       
+
       
    def example_title_open(self, token: Token, tokens: Sequence[Token], i: int) -> str:

     

       
225
       
+
       
        raise RuntimeError("md token not supported", token)

     

       
226
       
+
       
    def example_title_close(self, token: Token, tokens: Sequence[Token], i: int) -> str:

     

       
227
       
 
       
        raise RuntimeError("md token not supported", token)

     

       
228
       
 
       


     

       
229
       
 
       
def _is_escaped(src: str, pos: int) -> bool:

     
···

       
423
       
 
       


     

       
424
       
 
       
    md.core.ruler.push("block_attr", block_attr)

     

       
425
       
 
       


     

       
426
       
+
       
def _example_titles(md: markdown_it.MarkdownIt) -> None:

     

       
427
       
+
       
    """

     

       
428
       
+
       
    find title headings of examples and stick them into meta for renderers, then

     

       
429
       
+
       
    remove them from the token stream. also checks whether any example contains a

     

       
430
       
+
       
    non-title heading since those would make toc generation extremely complicated.

     

       
431
       
+
       
    """

     

       
432
       
+
       
    def example_titles(state: markdown_it.rules_core.StateCore) -> None:

     

       
433
       
+
       
        in_example = [False]

     

       
434
       
+
       
        for i, token in enumerate(state.tokens):

     

       
435
       
+
       
            if token.type == 'example_open':

     

       
436
       
+
       
                if state.tokens[i + 1].type == 'heading_open':

     

       
437
       
+
       
                    assert state.tokens[i + 3].type == 'heading_close'

     

       
438
       
+
       
                    state.tokens[i + 1].type = 'example_title_open'

     

       
439
       
+
       
                    state.tokens[i + 3].type = 'example_title_close'

     

       
440
       
+
       
                else:

     

       
441
       
+
       
                    assert token.map

     

       
442
       
+
       
                    raise RuntimeError(f"found example without title in line {token.map[0] + 1}")

     

       
443
       
+
       
                in_example.append(True)

     

       
444
       
+
       
            elif token.type == 'example_close':

     

       
445
       
+
       
                in_example.pop()

     

       
446
       
+
       
            elif token.type == 'heading_open' and in_example[-1]:

     

       
447
       
+
       
                assert token.map

     

       
448
       
+
       
                raise RuntimeError(f"unexpected non-title heading in example in line {token.map[0] + 1}")

     

       
449
       
+
       


     

       
450
       
+
       
    md.core.ruler.push("example_titles", example_titles)

     

       
451
       
+
       


     

       
452
       
 
       
TR = TypeVar('TR', bound='Renderer')

     

       
453
       
 
       


     

       
454
       
 
       
class Converter(ABC, Generic[TR]):

     
···

       
491
       
 
       
        self._md.use(_heading_ids)

     

       
492
       
 
       
        self._md.use(_compact_list_attr)

     

       
493
       
 
       
        self._md.use(_block_attr)

     

       
494
       
+
       
        self._md.use(_example_titles)

     

       
495
       
 
       
        self._md.enable(["smartquotes", "replacements"])

     

       
496
       
 
       


     

       
497
       
 
       
    def _parse(self, src: str) -> list[Token]:

     

···

       
1
       
 
       
import nixos_render_docs as nrd

     

       
0
       
 
       

     

       
2
       
 
       


     

       
3
       
 
       
from markdown_it.token import Token

     

       
4
       
 
       


     
···

       
427
       
 
       


     

       
428
       
 
       
def test_example() -> None:

     

       
429
       
 
       
    c = Converter({})

     

       
430
       
-
       
    assert c._parse("::: {.example}") == [

     

       
431
       
-
       
        Token(type='example_open', tag='div', nesting=1, attrs={}, map=[0, 1], level=0, children=None,

     

       
432
       
 
       
              content='', markup=':::', info=' {.example}', meta={}, block=True, hidden=False),

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
433
       
 
       
        Token(type='example_close', tag='div', nesting=-1, attrs={}, map=None, level=0, children=None,

     

       
434
       
-
       
              content='', markup=':::', info='', meta={}, block=True, hidden=False)

     

       
435
       
 
       
    ]

     

       
436
       
-
       
    assert c._parse("::: {#eid .example}") == [

     

       
437
       
-
       
        Token(type='example_open', tag='div', nesting=1, attrs={'id': 'eid'}, map=[0, 1], level=0,

     

       
438
       
 
       
              children=None, content='', markup=':::', info=' {#eid .example}', meta={}, block=True,

     

       
439
       
 
       
              hidden=False),

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
440
       
 
       
        Token(type='example_close', tag='div', nesting=-1, attrs={}, map=None, level=0, children=None,

     

       
441
       
-
       
              content='', markup=':::', info='', meta={}, block=True, hidden=False)

     

       
442
       
 
       
    ]

     

       
443
       
 
       
    assert c._parse("::: {.example .note}") == [

     

       
444
       
 
       
        Token(type='paragraph_open', tag='p', nesting=1, attrs={}, map=[0, 1], level=0, children=None,

     
···

       
452
       
 
       
        Token(type='paragraph_close', tag='p', nesting=-1, attrs={}, map=None, level=0, children=None,

     

       
453
       
 
       
              content='', markup='', info='', meta={}, block=True, hidden=False)

     

       
454
       
 
       
    ]

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

···

       
1
       
 
       
import nixos_render_docs as nrd

     

       
2
       
+
       
import pytest

     

       
3
       
 
       


     

       
4
       
 
       
from markdown_it.token import Token

     

       
5
       
 
       


     
···

       
428
       
 
       


     

       
429
       
 
       
def test_example() -> None:

     

       
430
       
 
       
    c = Converter({})

     

       
431
       
+
       
    assert c._parse("::: {.example}\n# foo") == [

     

       
432
       
+
       
        Token(type='example_open', tag='div', nesting=1, attrs={}, map=[0, 2], level=0, children=None,

     

       
433
       
 
       
              content='', markup=':::', info=' {.example}', meta={}, block=True, hidden=False),

     

       
434
       
+
       
        Token(type='example_title_open', tag='h1', nesting=1, attrs={}, map=[1, 2], level=1, children=None,

     

       
435
       
+
       
              content='', markup='#', info='', meta={}, block=True, hidden=False),

     

       
436
       
+
       
        Token(type='inline', tag='', nesting=0, attrs={}, map=[1, 2], level=2,

     

       
437
       
+
       
              content='foo', markup='', info='', meta={}, block=True, hidden=False,

     

       
438
       
+
       
              children=[

     

       
439
       
+
       
                  Token(type='text', tag='', nesting=0, attrs={}, map=None, level=0, children=None,

     

       
440
       
+
       
                        content='foo', markup='', info='', meta={}, block=False, hidden=False)

     

       
441
       
+
       
              ]),

     

       
442
       
+
       
        Token(type='example_title_close', tag='h1', nesting=-1, attrs={}, map=None, level=1, children=None,

     

       
443
       
+
       
              content='', markup='#', info='', meta={}, block=True, hidden=False),

     

       
444
       
 
       
        Token(type='example_close', tag='div', nesting=-1, attrs={}, map=None, level=0, children=None,

     

       
445
       
+
       
              content='', markup='', info='', meta={}, block=True, hidden=False)

     

       
446
       
 
       
    ]

     

       
447
       
+
       
    assert c._parse("::: {#eid .example}\n# foo") == [

     

       
448
       
+
       
        Token(type='example_open', tag='div', nesting=1, attrs={'id': 'eid'}, map=[0, 2], level=0,

     

       
449
       
 
       
              children=None, content='', markup=':::', info=' {#eid .example}', meta={}, block=True,

     

       
450
       
 
       
              hidden=False),

     

       
451
       
+
       
        Token(type='example_title_open', tag='h1', nesting=1, attrs={}, map=[1, 2], level=1, children=None,

     

       
452
       
+
       
              content='', markup='#', info='', meta={}, block=True, hidden=False),

     

       
453
       
+
       
        Token(type='inline', tag='', nesting=0, attrs={}, map=[1, 2], level=2,

     

       
454
       
+
       
              content='foo', markup='', info='', meta={}, block=True, hidden=False,

     

       
455
       
+
       
              children=[

     

       
456
       
+
       
                  Token(type='text', tag='', nesting=0, attrs={}, map=None, level=0, children=None,

     

       
457
       
+
       
                        content='foo', markup='', info='', meta={}, block=False, hidden=False)

     

       
458
       
+
       
              ]),

     

       
459
       
+
       
        Token(type='example_title_close', tag='h1', nesting=-1, attrs={}, map=None, level=1, children=None,

     

       
460
       
+
       
              content='', markup='#', info='', meta={}, block=True, hidden=False),

     

       
461
       
 
       
        Token(type='example_close', tag='div', nesting=-1, attrs={}, map=None, level=0, children=None,

     

       
462
       
+
       
              content='', markup='', info='', meta={}, block=True, hidden=False)

     

       
463
       
 
       
    ]

     

       
464
       
 
       
    assert c._parse("::: {.example .note}") == [

     

       
465
       
 
       
        Token(type='paragraph_open', tag='p', nesting=1, attrs={}, map=[0, 1], level=0, children=None,

     
···

       
473
       
 
       
        Token(type='paragraph_close', tag='p', nesting=-1, attrs={}, map=None, level=0, children=None,

     

       
474
       
 
       
              content='', markup='', info='', meta={}, block=True, hidden=False)

     

       
475
       
 
       
    ]

     

       
476
       
+
       
    assert c._parse("::: {.example}\n### foo: `code`\nbar\n:::\nbaz") == [

     

       
477
       
+
       
        Token(type='example_open', tag='div', nesting=1, map=[0, 3], markup=':::', info=' {.example}',

     

       
478
       
+
       
              block=True),

     

       
479
       
+
       
        Token(type='example_title_open', tag='h3', nesting=1, map=[1, 2], level=1, markup='###', block=True),

     

       
480
       
+
       
        Token(type='inline', tag='', nesting=0, map=[1, 2], level=2, content='foo: `code`', block=True,

     

       
481
       
+
       
              children=[

     

       
482
       
+
       
                  Token(type='text', tag='', nesting=0, content='foo: '),

     

       
483
       
+
       
                  Token(type='code_inline', tag='code', nesting=0, content='code', markup='`')

     

       
484
       
+
       
              ]),

     

       
485
       
+
       
        Token(type='example_title_close', tag='h3', nesting=-1, level=1, markup='###', block=True),

     

       
486
       
+
       
        Token(type='paragraph_open', tag='p', nesting=1, map=[2, 3], level=1, block=True),

     

       
487
       
+
       
        Token(type='inline', tag='', nesting=0, map=[2, 3], level=2, content='bar', block=True,

     

       
488
       
+
       
              children=[

     

       
489
       
+
       
                  Token(type='text', tag='', nesting=0, content='bar')

     

       
490
       
+
       
              ]),

     

       
491
       
+
       
        Token(type='paragraph_close', tag='p', nesting=-1, level=1, block=True),

     

       
492
       
+
       
        Token(type='example_close', tag='div', nesting=-1, markup=':::', block=True),

     

       
493
       
+
       
        Token(type='paragraph_open', tag='p', nesting=1, map=[4, 5], block=True),

     

       
494
       
+
       
        Token(type='inline', tag='', nesting=0, map=[4, 5], level=1, content='baz', block=True,

     

       
495
       
+
       
              children=[

     

       
496
       
+
       
                  Token(type='text', tag='', nesting=0, content='baz')

     

       
497
       
+
       
              ]),

     

       
498
       
+
       
        Token(type='paragraph_close', tag='p', nesting=-1, block=True)

     

       
499
       
+
       
    ]

     

       
500
       
+
       


     

       
501
       
+
       
    with pytest.raises(RuntimeError) as exc:

     

       
502
       
+
       
        c._parse("::: {.example}\n### foo\n### bar\n:::")

     

       
503
       
+
       
    assert exc.value.args[0] == 'unexpected non-title heading in example in line 3'