nixos-render-docs: require headings to have ids

without this we cannot build a TOC to arbitrary depth without generating
ids for headings, but generated ids are fragile and liable to either
break or point to different things if the manual changes shape. we
already have the convention that all headings should have an id, this
formalizes it.

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

@@ -32,6 +32,14 @@ def check_titles(kind: TocEntryType, tokens: Sequence[Token]) -> None:
     for token in tokens:
         if token.type != 'heading_open':
             continue
+
+        # book subtitle headings do not need an id, only book title headings do.
+        # every other headings needs one too. we need this to build a TOC and to
+        # provide stable links if the manual changes shape.
+        if 'id' not in token.attrs and (kind != 'book' or token.tag != 'h2'):
+            assert token.map
+            raise RuntimeError(f"heading in line {token.map[0] + 1} does not have an id")
+
         level = int(token.tag[1:]) # because tag = h1..h6
         if level > last_heading_level + 1:
             assert token.map