doc: Cross-reference roles syntax doc & implementation

[Zocker1999NET]

reasoning:

• (doc -> code) make it easier to find where those are implemented
  • to get easier insight if/what a specific renderer does with it
  • in case one wants to improve them, which seems likely as they are rather Nix/NixOS-specific
  • (took me too long to find their implementation)
• (code -> doc) ensure changes to the code can be reflected in the doc
  • code authors might not know about the reference documentation or how to find it

Things done

• Built on platform(s)
  • x86_64-linux
  • aarch64-linux
  • x86_64-darwin
  • aarch64-darwin
• For non-Linux: Is sandboxing enabled in nix.conf? (See Nix manual)
  • sandbox = relaxed
  • sandbox = true
• Tested, as applicable:
  • NixOS test(s) (look inside nixos/tests)
  • and/or package tests
  • or, for functions and "core" functionality, tests in lib/tests or pkgs/test
  • made sure NixOS tests are linked to the relevant packages
• Tested compilation of all packages that depend on this change using nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD". Note: all changes have to be committed, also see nixpkgs-review usage
• Tested basic functionality of all binary files (usually in ./result/bin/)
• 25.05 Release Notes (or backporting 24.11 and 25.05 Release notes)
  • (Package updates) Added a release notes entry if the change is major or breaking
  • (Module updates) Added a release notes entry if the change is significant
  • (Module addition) Added a release notes entry if adding a new NixOS module
• Fits CONTRIBUTING.md.

---

Add a 👍 reaction to pull requests you find important.

[Zocker1999NET]

If someone of you knows more about this (non-blocking): This line of the AsciiDoc renderer looks like a wildcard for some roles: https://github.com/Zocker1999NET/nixpkgs/blob/3c20746f99537b0c8bf42ceef162fe73cdef7c77/pkgs/by-name/ni/nixos-render-docs/src/nixos_render_docs/asciidoc.py#L190

But I have not found if this is there to use AsciiDoc native roles (& where those are documented) or if there is some CSS file or so where those are handled. In case this is not native, I think referencing docs/README.md from there as well would be useful too.

[fricklerhandwerk]

Looks good, at least not wrong - I'm not an expert on this code.

Not exactly sure, but the long term correct way to do this may be some sort of auto generation of docs, but that would likely require tearing apart all of the code.