commit 407f6196a23f8b0b42c74c66f2717645aa277bbd · pyrox.dev/nixpkgs

+1 -1

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

···

       13
       13
        
       submodules.

     

       14
       14
        
       

     

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

     

       16
       16
       -
       **Example: Freeform submodule**

     

       16
       16
       +
       ### Freeform submodule

     

       17
       17
        
       

     

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

     

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

+7 -3

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

···

       77
       77
        
       For example:

     

       78
       78
        
       

     

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

     

       80
       80
       +
       ### `mkEnableOption` usage

     

       80
       81
        
       ```nix

     

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

     

       82
       83
        
       # is like

     
···

       126
       127
        
       Examples:

     

       127
       128
        
       

     

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

     

       130
       130
       +
       ### Simple `mkPackageOption` usage

     

       129
       131
        
       ```nix

     

       130
       132
        
       lib.mkPackageOptionMD pkgs "hello" { }

     

       131
       133
        
       # is like

     
···

       139
       141
        
       :::

     

       140
       142
        
       

     

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

     

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

     

       142
       145
        
       ```nix

     

       143
       146
        
       lib.mkPackageOptionMD pkgs "GHC" {

     

       144
       147
        
         default = [ "ghc" ];

     
···

       156
       159
        
       :::

     

       157
       160
        
       

     

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

     

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

     

       159
       163
        
       ```nix

     

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

     

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

     
···

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

     

       218
       222
        
       

     

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

     

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

     

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

     

       221
       225
        
       ```nix

     

       222
       226
        
       services.xserver.displayManager.enable = mkOption {

     

       223
       227
        
         description = "Display manager to use";

     
···

       227
       231
        
       :::

     

       228
       232
        
       

     

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

     

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

     

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

     

       231
       235
        
       ```nix

     

       232
       236
        
       services.xserver.displayManager.enable = mkOption {

     

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

     
···

       236
       240
        
       :::

     

       237
       241
        
       

     

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

     

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

     

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

     

       240
       244
        
       ```nix

     

       241
       245
        
       services.xserver.displayManager.enable = mkOption {

     

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

+9 -9

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

···

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

     

       37
       37
        
       

     

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

     

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

     

       39
       39
       +
           ### `types.anything`

     

       40
       40
        
       

     

       41
       41
        
           Two definitions of this type like

     

       42
       42
        
       

     
···

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

     

       357
       357
        
       

     

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

     

       359
       359
       -
       **Example: Directly defined submodule**

     

       359
       359
       +
       ### Directly defined submodule

     

       360
       360
        
       ```nix

     

       361
       361
        
       options.mod = mkOption {

     

       362
       362
        
         description = "submodule example";

     
···

       375
       375
        
       :::

     

       376
       376
        
       

     

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

     

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

     

       378
       378
       +
       ### Submodule defined as a reference

     

       379
       379
        
       ```nix

     

       380
       380
        
       let

     

       381
       381
        
         modOptions = {

     
···

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

     

       404
       404
        
       

     

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

     

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

     

       406
       406
       +
       ### Declaration of a list of submodules

     

       407
       407
        
       ```nix

     

       408
       408
        
       options.mod = mkOption {

     

       409
       409
        
         description = "submodule example";

     
···

       422
       422
        
       :::

     

       423
       423
        
       

     

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

     

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

     

       425
       425
       +
       ### Definition of a list of submodules

     

       426
       426
        
       ```nix

     

       427
       427
        
       config.mod = [

     

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

     
···

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

     

       438
       438
        
       

     

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

     

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

     

       440
       440
       +
       ### Declaration of attribute sets of submodules

     

       441
       441
        
       ```nix

     

       442
       442
        
       options.mod = mkOption {

     

       443
       443
        
         description = "submodule example";

     
···

       456
       456
        
       :::

     

       457
       457
        
       

     

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

     

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

     

       459
       459
       +
       ### Definition of attribute sets of submodules

     

       460
       460
        
       ```nix

     

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

     

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

     
···

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

     

       477
       477
        
       

     

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

     

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

     

       479
       479
       +
           ### Adding a type check

     

       480
       480
        
       

     

       481
       481
        
           ```nix

     

       482
       482
        
           byte = mkOption {

     
···

       487
       487
        
           :::

     

       488
       488
        
       

     

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

     

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

     

       490
       490
       +
           ### Overriding a type check

     

       491
       491
        
       

     

       492
       492
        
           ```nix

     

       493
       493
        
           nixThings = mkOption {

+2 -2

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

···

       143
       143
        
           :::

     

       144
       144
        
       

     

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

     

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

     

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

     

       147
       147
        
       

     

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

     

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

     
···

       218
       218
        
       up in the manual.

     

       219
       219
        
       

     

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

     

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

     

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

     

       222
       222
        
       ```nix

     

       223
       223
        
       settings = lib.mkOption {

     

       224
       224
        
         type = lib.types.submodule {

+3 -3

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

···

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

     

       38
       38
        
       

     

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

     

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

     

       40
       40
       +
       ### Structure of NixOS Modules

     

       41
       41
        
       ```nix

     

       42
       42
        
       { config, pkgs, ... }:

     

       43
       43
        
       

     
···

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

     

       101
       101
        
       

     

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

     

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

     

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

     

       104
       104
        
       ```nix

     

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

     

       106
       106
        
       

     
···

       161
       161
        
       :::

     

       162
       162
        
       

     

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

     

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

     

       164
       164
       +
       ### Escaping in Exec directives

     

       165
       165
        
       ```nix

     

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

     

       167
       167

+4 -4

nixos/doc/manual/installation/installing.chapter.md

···

       538
       538
        
       corresponding configuration Nix expression.

     

       539
       539
        
       

     

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

     

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

     

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

     

       542
       542
        
       ```ShellSession

     

       543
       543
        
       # parted /dev/sda -- mklabel msdos

     

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

     
···

       547
       547
        
       :::

     

       548
       548
        
       

     

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

     

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

     

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

     

       551
       551
        
       ```ShellSession

     

       552
       552
        
       # parted /dev/sda -- mklabel gpt

     

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

     
···

       558
       558
        
       :::

     

       559
       559
        
       

     

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

     

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

     

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

     

       562
       562
        
       

     

       563
       563
        
       With a partitioned disk.

     

       564
       564
        
       

     
···

       578
       578
        
       :::

     

       579
       579
        
       

     

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

     

       581
       581
       -
       **Example: NixOS Configuration**

     

       581
       581
       +
       ### Example: NixOS Configuration

     

       582
       582
        
       ```ShellSession

     

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

     

       584
       584
        
         imports = [

+8 -4

pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/docbook.py

···

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

     

       219
       219
        
               return result

     

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

     

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

     

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

     

       223
       223
       -
               return ""

     

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

     

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

     

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

     

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

     

       225
       225
       -
               return ""

     

       225
       225
       +
               return "</example>"

     

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

     

       227
       227
       +
               return "<title>"

     

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

     

       229
       229
       +
               return "</title>"

     

       226
       230
        
       

     

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

     

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

+8 -4

pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/html.py

···

       214
       214
        
               self._ordered_list_nesting -= 1;

     

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

     

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

     

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

     

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

     

       219
       219
       -
               return ""

     

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

     

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

     

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

     

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

     

       221
       221
       -
               return ""

     

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

     

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

     

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

     

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

     

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

     

       222
       226
        
       

     

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

     

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

+40

pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/manual.py

···

       402
       402
        
               )

     

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

     

       404
       404
        
                   return ""

     

       405
       405
       +
               examples = ""

     

       406
       406
       +
               if toc.examples:

     

       407
       407
       +
                   examples_entries = [

     

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

     

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

     

       410
       410
       +
                   ]

     

       411
       411
       +
                   examples = (

     

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

     

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

     

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

     

       415
       415
       +
                       '</div>'

     

       416
       416
       +
                   )

     

       405
       417
        
               return (

     

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

     

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

     
···

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

     

       410
       422
        
                   f' </dl>'

     

       411
       423
        
                   f'</div>'

     

       424
       424
       +
                   f'{examples}'

     

       412
       425
        
               )

     

       413
       426
        
       

     

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

     
···

       513
       526
        
                   self._redirection_targets.add(into)

     

       514
       527
        
               return tokens

     

       515
       528
        
       

     

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

     

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

     

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

     

       532
       532
       +
                       title = tokens[i + 1]

     

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

     

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

     

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

     

       536
       536
       +
                       title.children = (

     

       537
       537
       +
                           [

     

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

     

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

     

       540
       540
       +
                           ] + title.children

     

       541
       541
       +
                       )

     

       542
       542
       +
                       start += 1

     

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

     

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

     

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

     

       546
       546
       +
               return start

     

       547
       547
       +
       

     

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

     

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

     

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

     
···

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

     

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

     

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

     

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

     

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

     

       537
       571
        
                   elif bt.type == 'inline':

     

       538
       572
        
                       assert bt.children

     

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

     
···

       558
       592
        
                   title = prefix + title_html

     

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

     

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

     

       595
       595
       +
               elif typ == 'example':

     

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

     

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

     

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

     

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

     

       561
       600
        
               else:

     

       562
       601
        
                   toc_html, title = title_html, title_html

     

       563
       602
        
                   title_html = (

     
···

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

     

       570
       609
        
       

     

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

     

       611
       611
       +
               self._number_examples(tokens)

     

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

     

       573
       613
        
       

     

       574
       614
        
               failed = False

+15 -7

pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/manual_structure.py

···

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

     

       15
       15
        
       

     

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

     

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

     

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

     

       18
       18
        
       

     

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

     

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

     
···

       124
       124
        
           next: TocEntry | None = None

     

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

     

       126
       126
        
           starts_new_chunk: bool = False

     

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

     

       127
       128
        
       

     

       128
       129
        
           @property

     

       129
       130
        
           def root(self) -> TocEntry:

     
···

       138
       139
        
       

     

       139
       140
        
           @classmethod

     

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

     

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

     

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

     

       142
       143
        
       

     

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

     

       144
       145
        
                   this.parent = parent

     

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

     

       146
       147
        
       

     

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

     

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

     

       148
       149
        
               prev = flat[0]

     

       149
       150
        
               prev.starts_new_chunk = True

     

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

     
···

       155
       156
        
                       prev = c

     

       156
       157
        
                   paths_seen.add(c.target.path)

     

       157
       158
        
       

     

       159
       159
       +
               flat[0].examples = examples

     

       160
       160
       +
       

     

       158
       161
        
               for c in flat:

     

       159
       162
        
                   c.freeze()

     

       160
       163
        
       

     

       161
       161
       -
               return result

     

       164
       164
       +
               return entries

     

       162
       165
        
       

     

       163
       166
        
           @classmethod

     

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

     

       165
       165
       -
                                kind: TocEntryType) -> TocEntry:

     

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

     

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

     

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

     

       168
       171
        
               # the full sequence.

     

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

     

       173
       173
       +
               examples: list[TocEntry] = []

     

       170
       174
        
               for token in tokens:

     

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

     

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

     

       173
       177
        
                       assert fragment_type_str in get_args(TocEntryType)

     

       174
       178
        
                       fragment_type = cast(TocEntryType, fragment_type_str)

     

       175
       179
        
                       for fragment, _path in included:

     

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

     

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

     

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

     

       182
       182
       +
                           examples += subexamples

     

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

     

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

     

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

     

       180
       186
        
                       entries.append((token.tag,

     

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

     

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

     

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

     

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

     

       183
       191
        
       

     

       184
       192
        
               while len(entries) > 1:

     

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

     

       186
       186
       -
               return entries[0][1]

     

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

+33

pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/md.py

···

       88
       88
        
                   "ordered_list_close": self.ordered_list_close,

     

       89
       89
        
                   "example_open": self.example_open,

     

       90
       90
        
                   "example_close": self.example_close,

     

       91
       91
       +
                   "example_title_open": self.example_title_open,

     

       92
       92
       +
                   "example_title_close": self.example_title_close,

     

       91
       93
        
               }

     

       92
       94
        
       

     

       93
       95
        
               self._admonitions = {

     
···

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

     

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

     

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

     

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

     

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

     

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

     

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

     

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

     

       222
       228
        
       

     

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

     
···

       417
       423
        
       

     

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

     

       419
       425
        
       

     

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

     

       427
       427
       +
           """

     

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

     

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

     

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

     

       431
       431
       +
           """

     

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

     

       433
       433
       +
               in_example = [False]

     

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

     

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

     

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

     

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

     

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

     

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

     

       440
       440
       +
                       else:

     

       441
       441
       +
                           assert token.map

     

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

     

       443
       443
       +
                       in_example.append(True)

     

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

     

       445
       445
       +
                       in_example.pop()

     

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

     

       447
       447
       +
                       assert token.map

     

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

     

       449
       449
       +
       

     

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

     

       451
       451
       +
       

     

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

     

       421
       453
        
       

     

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

     
···

       459
       491
        
               self._md.use(_heading_ids)

     

       460
       492
        
               self._md.use(_compact_list_attr)

     

       461
       493
        
               self._md.use(_block_attr)

     

       494
       494
       +
               self._md.use(_example_titles)

     

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

     

       463
       496
        
       

     

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

+55 -6

pkgs/tools/nix/nixos-render-docs/src/tests/test_plugins.py

···

       1
       1
        
       import nixos_render_docs as nrd

     

       2
       2
       +
       import pytest

     

       2
       3
        
       

     

       3
       4
        
       from markdown_it.token import Token

     

       4
       5
        
       

     
···

       427
       428
        
       

     

       428
       429
        
       def test_example() -> None:

     

       429
       430
        
           c = Converter({})

     

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

     

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

     

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

     

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

     

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

     

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

     

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

     

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

     

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

     

       438
       438
       +
                     children=[

     

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

     

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

     

       441
       441
       +
                     ]),

     

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

     

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

     

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

     

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

     

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

     

       435
       446
        
           ]

     

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

     

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

     

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

     

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

     

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

     

       439
       450
        
                     hidden=False),

     

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

     

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

     

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

     

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

     

       455
       455
       +
                     children=[

     

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

     

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

     

       458
       458
       +
                     ]),

     

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

     

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

     

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

     

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

     

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

     

       442
       463
        
           ]

     

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

     

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

     
···

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

     

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

     

       454
       475
        
           ]

     

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

     

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

     

       478
       478
       +
                     block=True),

     

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

     

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

     

       481
       481
       +
                     children=[

     

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

     

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

     

       484
       484
       +
                     ]),

     

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

     

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

     

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

     

       488
       488
       +
                     children=[

     

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

     

       490
       490
       +
                     ]),

     

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

     

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

     

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

     

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

     

       495
       495
       +
                     children=[

     

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

     

       497
       497
       +
                     ]),

     

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

     

       499
       499
       +
           ]

     

       500
       500
       +
       

     

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

     

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

     

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