commit 8fb4cf8b7c6f9d180a59e0f33405bc6a61e24d60 · pyrox.dev/nixpkgs

+20

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

···

       237
        
                   f'<img src="{escape(src, True)}" {alt} {title} />'

     

       238
        
                   '</div>'

     

       239
        
               )

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       240
        
       

     

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

     

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

···

       237
        
                   f'<img src="{escape(src, True)}" {alt} {title} />'

     

       238
        
                   '</div>'

     

       239
        
               )

     

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

     

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

     

       242
       +
                   anchor = f'<a id="{escape(anchor, True)}"></a>'

     

       243
       +
               return f'<div class="figure">{anchor}'

     

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

     

       245
       +
               return (

     

       246
       +
                   ' </div>'

     

       247
       +
                   '</div><br class="figure-break" />'

     

       248
       +
               )

     

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

     

       250
       +
               return (

     

       251
       +
                   '<p class="title">'

     

       252
       +
                   ' <strong>'

     

       253
       +
               )

     

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

     

       255
       +
               return (

     

       256
       +
                   ' </strong>'

     

       257
       +
                   '</p>'

     

       258
       +
                   '<div class="figure-contents">'

     

       259
       +
               )

     

       260
        
       

     

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

     

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

+21 -14

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

···

       426
        
                       if next_level:

     

       427
        
                           result.append(f'<dd><dl>{"".join(next_level)}</dl></dd>')

     

       428
        
                   return result

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       429
        
               # we don't want to generate the "Title of Contents" header for sections,

     

       430
        
               # docbook doesn't and it's only distracting clutter unless it's the main table.

     

       431
        
               # we also want to generate tocs only for a top-level section (ie, one that is

     
···

       442
        
                   toc_depth = self._html_params.toc_depth

     

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

     

       444
        
                   return ""

     

       445
       -
               examples = ""

     

       446
       -
               if toc.examples:

     

       447
       -
                   examples_entries = [

     

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

     

       449
       -
                       for i, ex in enumerate(toc.examples)

     

       450
       -
                   ]

     

       451
       -
                   examples = (

     

       452
       -
                       '<div class="list-of-examples">'

     

       453
       -
                       '<p><strong>List of Examples</strong></p>'

     

       454
       -
                       f'<dl>{"".join(examples_entries)}</dl>'

     

       455
       -
                       '</div>'

     

       456
       -
                   )

     

       457
        
               return "".join([

     

       458
        
                   f'<div class="toc">',

     

       459
        
                   ' <p><strong>Table of Contents</strong></p>' if print_title else "",

     
···

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

     

       462
        
                   f' </dl>'

     

       463
        
                   f'</div>'

     

       0
        
       
     

       464
        
                   f'{examples}'

     

       465
        
               ])

     

       466
        
       

     
···

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

     

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

     

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

     

       0
        
       
     

       0
        
       
     

       615
        
                   elif bt.type == 'inline':

     

       616
        
                       assert bt.children

     

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

     
···

       636
        
                   title = prefix + title_html

     

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

     

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

     

       639
       -
               elif typ == 'example':

     

       640
       -
                   # skip the prepended `Example N. ` from numbering

     

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

     

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

     

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

     
···

       653
        
       

     

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

     

       655
        
               self._number_block('example', "Example", tokens)

     

       0
        
       
     

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

     

       657
        
       

     

       658
        
               failed = False

···

       426
        
                       if next_level:

     

       427
        
                           result.append(f'<dd><dl>{"".join(next_level)}</dl></dd>')

     

       428
        
                   return result

     

       429
       +
               def build_list(kind: str, id: str, lst: Sequence[TocEntry]) -> str:

     

       430
       +
                   if not lst:

     

       431
       +
                       return ""

     

       432
       +
                   entries = [

     

       433
       +
                       f'<dt>{i}. <a href="{e.target.href()}">{e.target.toc_html}</a></dt>'

     

       434
       +
                       for i, e in enumerate(lst, start=1)

     

       435
       +
                   ]

     

       436
       +
                   return (

     

       437
       +
                       f'<div class="{id}">'

     

       438
       +
                       f'<p><strong>List of {kind}</strong></p>'

     

       439
       +
                       f'<dl>{"".join(entries)}</dl>'

     

       440
       +
                       '</div>'

     

       441
       +
                   )

     

       442
        
               # we don't want to generate the "Title of Contents" header for sections,

     

       443
        
               # docbook doesn't and it's only distracting clutter unless it's the main table.

     

       444
        
               # we also want to generate tocs only for a top-level section (ie, one that is

     
···

       455
        
                   toc_depth = self._html_params.toc_depth

     

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

     

       457
        
                   return ""

     

       458
       +
               figures = build_list("Figures", "list-of-figures", toc.figures)

     

       459
       +
               examples = build_list("Examples", "list-of-examples", toc.examples)

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       460
        
               return "".join([

     

       461
        
                   f'<div class="toc">',

     

       462
        
                   ' <p><strong>Table of Contents</strong></p>' if print_title else "",

     
···

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

     

       465
        
                   f' </dl>'

     

       466
        
                   f'</div>'

     

       467
       +
                   f'{figures}'

     

       468
        
                   f'{examples}'

     

       469
        
               ])

     

       470
        
       

     
···

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

     

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

     

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

     

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

     

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

     

       621
        
                   elif bt.type == 'inline':

     

       622
        
                       assert bt.children

     

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

     
···

       642
        
                   title = prefix + title_html

     

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

     

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

     

       645
       +
               elif typ in ['example', 'figure']:

     

       646
       +
                   # skip the prepended `{Example,Figure} N. ` from numbering

     

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

     

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

     

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

     
···

       659
        
       

     

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

     

       661
        
               self._number_block('example', "Example", tokens)

     

       662
       +
               self._number_block('figure', "Figure", tokens)

     

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

     

       664
        
       

     

       665
        
               failed = False

+11 -5

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

···

       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=} ")

     
···

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

     

       129
        
           starts_new_chunk: bool = False

     

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

     

       0
        
       
     

       131
        
       

     

       132
        
           @property

     

       133
        
           def root(self) -> TocEntry:

     
···

       142
        
       

     

       143
        
           @classmethod

     

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

     

       145
       -
               entries, examples = cls._collect_entries(xrefs, tokens, 'book')

     

       146
        
       

     

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

     

       148
        
                   this.parent = parent

     
···

       160
        
                   paths_seen.add(c.target.path)

     

       161
        
       

     

       162
        
               flat[0].examples = examples

     

       0
        
       
     

       163
        
       

     

       164
        
               for c in flat:

     

       165
        
                   c.freeze()

     
···

       168
        
       

     

       169
        
           @classmethod

     

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

     

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

     

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

     

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

     

       174
        
               # the full sequence.

     

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

     

       176
        
               examples: list[TocEntry] = []

     

       0
        
       
     

       177
        
               for token in tokens:

     

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

     

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

     

       180
        
                       assert fragment_type_str in get_args(TocEntryType)

     

       181
        
                       fragment_type = cast(TocEntryType, fragment_type_str)

     

       182
        
                       for fragment, _path in included:

     

       183
       -
                           subentries, subexamples = cls._collect_entries(xrefs, fragment, fragment_type)

     

       184
        
                           entries[-1][1].children.append(subentries)

     

       185
        
                           examples += subexamples

     

       0
        
       
     

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

     

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

     

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

     
···

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

     

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

     

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

     

       0
        
       
     

       0
        
       
     

       194
        
       

     

       195
        
               while len(entries) > 1:

     

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

     

       197
       -
               return (entries[0][1], examples)

···

       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', 'figure']

     

       18
        
       

     

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

     

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

     
···

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

     

       129
        
           starts_new_chunk: bool = False

     

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

     

       131
       +
           figures: list[TocEntry] = dc.field(default_factory=list)

     

       132
        
       

     

       133
        
           @property

     

       134
        
           def root(self) -> TocEntry:

     
···

       143
        
       

     

       144
        
           @classmethod

     

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

     

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

     

       147
        
       

     

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

     

       149
        
                   this.parent = parent

     
···

       161
        
                   paths_seen.add(c.target.path)

     

       162
        
       

     

       163
        
               flat[0].examples = examples

     

       164
       +
               flat[0].figures = figures

     

       165
        
       

     

       166
        
               for c in flat:

     

       167
        
                   c.freeze()

     
···

       170
        
       

     

       171
        
           @classmethod

     

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

     

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

     

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

     

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

     

       176
        
               # the full sequence.

     

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

     

       178
        
               examples: list[TocEntry] = []

     

       179
       +
               figures: list[TocEntry] = []

     

       180
        
               for token in tokens:

     

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

     

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

     

       183
        
                       assert fragment_type_str in get_args(TocEntryType)

     

       184
        
                       fragment_type = cast(TocEntryType, fragment_type_str)

     

       185
        
                       for fragment, _path in included:

     

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

     

       187
        
                           entries[-1][1].children.append(subentries)

     

       188
        
                           examples += subexamples

     

       189
       +
                           figures += subfigures

     

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

     

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

     

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

     
···

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

     

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

     

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

     

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

     

       199
       +
                       figures.append(TocEntry('figure', xrefs[id]))

     

       200
        
       

     

       201
        
               while len(entries) > 1:

     

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

     

       203
       +
               return (entries[0][1], examples, figures)

+21 -1

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

···

       40
        
           ticks, sep = ('`' * (longest + (3 if multiline else 1)), '\n' if multiline else ' ')

     

       41
        
           return f"{ticks}{info}{sep}{code}{sep}{ticks}"

     

       42
        
       

     

       43
       -
       AttrBlockKind = Literal['admonition', 'example']

     

       44
        
       

     

       45
        
       AdmonitionKind = Literal["note", "caution", "tip", "important", "warning"]

     

       46
        
       

     
···

       91
        
                   "example_title_open": self.example_title_open,

     

       92
        
                   "example_title_close": self.example_title_close,

     

       93
        
                   "image": self.image,

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       94
        
               }

     

       95
        
       

     

       96
        
               self._admonitions = {

     
···

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

     

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

     

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

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       231
        
       

     

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

     

       233
        
           found = 0

     
···

       270
        
               return ('admonition', id, classes)

     

       271
        
           if classes == ['example']:

     

       272
        
               return ('example', id, classes)

     

       0
        
       
     

       0
        
       
     

       273
        
           return None

     

       274
        
       

     

       275
        
       def _attr_span_plugin(md: markdown_it.MarkdownIt) -> None:

     
···

       419
        
                           if id is not None:

     

       420
        
                               token.attrs['id'] = id

     

       421
        
                           stack.append('example_close')

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       422
        
                       else:

     

       423
        
                           assert_never(kind)

     

       424
        
                   elif token.type == 'container_blockattr_close':

     
···

       501
        
               self._md.use(_compact_list_attr)

     

       502
        
               self._md.use(_block_attr)

     

       503
        
               self._md.use(_block_titles("example"))

     

       0
        
       
     

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

     

       505
        
       

     

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

···

       40
        
           ticks, sep = ('`' * (longest + (3 if multiline else 1)), '\n' if multiline else ' ')

     

       41
        
           return f"{ticks}{info}{sep}{code}{sep}{ticks}"

     

       42
        
       

     

       43
       +
       AttrBlockKind = Literal['admonition', 'example', 'figure']

     

       44
        
       

     

       45
        
       AdmonitionKind = Literal["note", "caution", "tip", "important", "warning"]

     

       46
        
       

     
···

       91
        
                   "example_title_open": self.example_title_open,

     

       92
        
                   "example_title_close": self.example_title_close,

     

       93
        
                   "image": self.image,

     

       94
       +
                   "figure_open": self.figure_open,

     

       95
       +
                   "figure_close": self.figure_close,

     

       96
       +
                   "figure_title_open": self.figure_title_open,

     

       97
       +
                   "figure_title_close": self.figure_title_close,

     

       98
        
               }

     

       99
        
       

     

       100
        
               self._admonitions = {

     
···

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

     

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

     

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

     

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

     

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

     

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

     

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

     

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

     

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

     

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

     

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

     

       243
        
       

     

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

     

       245
        
           found = 0

     
···

       282
        
               return ('admonition', id, classes)

     

       283
        
           if classes == ['example']:

     

       284
        
               return ('example', id, classes)

     

       285
       +
           elif classes == ['figure']:

     

       286
       +
               return ('figure', id, classes)

     

       287
        
           return None

     

       288
        
       

     

       289
        
       def _attr_span_plugin(md: markdown_it.MarkdownIt) -> None:

     
···

       433
        
                           if id is not None:

     

       434
        
                               token.attrs['id'] = id

     

       435
        
                           stack.append('example_close')

     

       436
       +
                       elif kind == 'figure':

     

       437
       +
                           token.type = 'figure_open'

     

       438
       +
                           if id is not None:

     

       439
       +
                               token.attrs['id'] = id

     

       440
       +
                           stack.append('figure_close')

     

       441
        
                       else:

     

       442
        
                           assert_never(kind)

     

       443
        
                   elif token.type == 'container_blockattr_close':

     
···

       520
        
               self._md.use(_compact_list_attr)

     

       521
        
               self._md.use(_block_attr)

     

       522
        
               self._md.use(_block_titles("example"))

     

       523
       +
               self._md.use(_block_titles("figure"))

     

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

     

       525
        
       

     

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