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