Most of the error messages in `nixos-render-docs` produce line numbers,
which would be really helpful if the sources being rendered weren't
often generated from `.nix` files themselves!
While the Python `markdown_it` library doesn't give us an obvious way to
track source provenance like this (i.e., mapping source spans in the
generated files to source spans in the input files), we can make the
errors a lot clearer by displaying the relevant lines from the source.
Below, an error message caused by a missing `:::` is made obvious by
displaying the span that composes the block being rendered, rather than
pointing only at the offending title.
Before:
```
caused by:
unexpected non-title heading in example in line 87
```
After:
```
caused by:
unexpected non-title heading in `:::{.example}`; are you missing a `:::`?
Note: blocks like `:::{.example}` are only allowed to contain a single heading in order to simplify TOC generation.
`:::{.example}` block at lines 76-112:
73 ┆ ```
74 ┆
75 ┆ ### Examples
76 ┃ :::{.example}
77 ┃ #### `lib.debug.traceValFn` usage example
78 ┃
79 ┃ ```nix
80 ┃ traceValFn (v: "mystring ${v}") "foo"
81 ┃ trace: mystring foo
82 ┃ => "foo"
83 ┃ ```
84 ┃
85 ┃ Located at [lib/debug.nix:106](https://github.com/NixOS/nixpkgs/blob/master/lib/debug.nix#L106) in `<nixpkgs>`.
...
103 ┃ ### Examples
104 ┃ :::{.example}
105 ┃ #### `lib.debug.traceVal` usage example
106 ┃
107 ┃ ```nix
108 ┃ traceVal 42
109 ┃ # trace: 42
110 ┃ => 42
111 ┃ ```
112 ┃
113 ┆ :::
114 ┆
115 ┆ Located at [lib/debug.nix:135](https://github.com/NixOS/nixpkgs/blob/master/lib/debug.nix#L135) in `<nixpkgs>`.
Unexpected heading at line 87:
84 ┆
85 ┆ Located at [lib/debug.nix:106](https://github.com/NixOS/nixpkgs/blob/master/lib/debug.nix#L106) in `<nixpkgs>`.
86 ┆
87 ┃ ## `lib.debug.traceVal` {#function-library-lib.debug.traceVal}
88 ┆
89 ┆ Trace the supplied value and return it.
90 ┆
```
Resolution still fails when on VPN with no IPv6 DNS servers. We'll need
to investigate further why the fix doesn't help in this case.
This reverts commit f90236a8f2.
Signed-off-by: Ihar Hrachyshka <ihar.hrachyshka@gmail.com>
Rebecca Turner