Nice! I think we should not just rip out the mdDoc definition but rather throw with an informative error message for another release.

infinisil, guardian of architectural sanity, please give your blessing.

Hey all

I could use some help with understanding how NRD works and how to document library files properly.

For reference, I am working on this PR that adds network functions to the nixpkgs library.
https://github.com/NixOS/nixpkgs/pull/299409

The manual is failing to build and when I try to build it locally I see this:

RuntimeError: failed to render manual manual.md
error:
        failed to render manual manual.md

caused by:
        rendering lib.md

caused by:
        rendering functions.md

caused by:
        rendering functions/library.md

caused by:
        rendering /nix/store/b94j5fg7rf3m7w6s76by60jd7hb1avry-nixpkgs-lib-docs/network.md

caused by:
bad local reference, id #function-library-lib.network.ipv4.fromCidrString not known

which i've determine to be caused by this line in the default.nix doc comment

  - [`lib.network.ipv4.fromCidrString`](#function-library-lib.network.ipv4.fromCidrString):

This makes sense that it can't find it because if I remove the line, it does build, but there is no documentation for the functions I have created in the manual.

Any advice?

okay more info I found out.

If i change the reference from

#function-library-lib.network.ipv4.fromCidrString

to

#function-library-lib.network.ipv4

it builds and renders fine

but ipv4 is just a namespace for all my functions inside of the network library. Can we not access functions inside of an attrset or do I need to write things differently so it works?

hey all, i recently got it into my head to write a little tool which automatically edits nix files without messing them up, and got it to a point where it can remove e.g. all mentions of lib.mdDoc from nixpkgs. I have a changeset of it applied to master or ~an hour ago here: https://github.com/NixOS/nixpkgs/compare/5d401f9ed627a869fd231f63e4f8380022dcded5...stuebinm:nixpkgs:eed6c7c5de883d78d8185adaf4949c0fb7f8f44f

i have not opened a pull request with it because that'd just ping a lot of people and i'm not sure if it would be accepted or people here would even be interested, so I thought I'd ask here beforehand

In reply to @terru:raccoon.college
fair enough (should it be an outright error or just a trace for now?). if nothing else comes up i'd open a PR with this built on then-current master sometime tomorrow