make-options-doc: Support Nix-provided declaration links

[roberth]

Description of changes

Previously, the location logic was hardcoded, supporting only
Nixpkgs and NixOps properly, leaving other uses of the module
system without good location support.

Usage is along the lines of

makeOptionsDoc {
  # ...
  transformOptions = opt:
    opt // { declarations = map (decl: { url = ...; name = ...; }) opt.declarations; };
}

Now also fixes the Nixpkgs config options doc file links. For broken links, see https://nixos.org/manual/nixpkgs/stable/#opt-allowAliases.

ping @rycee

Things done

• Built on platform(s)
  • x86_64-linux
    • NixOS manual renders as before
  • aarch64-linux
  • x86_64-darwin
  • aarch64-darwin
• For non-Linux: Is sandbox = true set in nix.conf? (See Nix manual)
• 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/)
• 22.05 Release Notes (or backporting 21.11 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
  • (Release notes changes) Ran nixos/doc/manual/md-to-db.sh to update generated release notes
• Fits CONTRIBUTING.md.

[infinisil]

Can we remove the special cases for NixOS and Nixops? Or at least push them out of the XSL file

[roberth]

Can we remove the special cases for NixOS and Nixops? Or at least push them out of the XSL file

That is the goal, but we'll need a migration window where both methods are available, at least for NixOps.

[roberth]

I'm also hesitant to migrate NixOS immediately because its list of options is huge and tiny per-option overhead may be significant.

[roberth]

I've described the follow-up work in #178572

[github-actions]

Successfully created backport PR #178573 for release-22.05.