make-options-doc: fix string context issues

[d-goldin]

Motivation for this change

When using documentation.nixos.includeAllModules = true; with external
modules, the string context might contain dependencies to derivations
and so toFile refuses to evaluate;

error: in 'toFile': the file 'options.xml' cannot refer to derivation outputs, at
[...]/nixpkgs/nixos/lib/make-options-doc/default.nix:89:16

This is not an issue when using writeText (instead of manually
stripping the context).

Possibly addresses: #73743

For my particular configuration utilizing home-manager this fix is insufficient, because some of the formatting for some home-manager options fail validation;

manual-combined.xml:19469: element link: validity error : IDREF attribute linkend references an unknown ID "opt-xsession.windowManager.i3.config.assigns"
[...]

But maybe this is one step forward anyways.

Things done

• Tested using sandboxing (nix.useSandbox on NixOS, or option sandbox in nix.conf on non-NixOS linux)
• Built on platform(s)
  • NixOS
  • macOS
  • other Linux distributions
• Tested via one or more NixOS test(s) if existing and applicable for the change (look inside nixos/tests)
• Tested compilation of all pkgs that depend on this change using nix-shell -p nix-review --run "nix-review wip"
• Tested execution of all binary files (usually in ./result/bin/)
• Determined the impact on package closure size (by running nix path-info -S before and after)
• Ensured that relevant documentation is up to date
• Fits CONTRIBUTING.md.

Notify maintainers

cc @domenkozar

[domenkozar]

iirc this will fail regardless, there should be no /nix/store paths in the manual (there's a check for that).

[d-goldin]

@domenkozar: I don't know those parts too well yet, but saw the check. The check emits a better error message in comparison to the toFile error. I thought it would make sense to get this out of the way in the context of documentation.nixos.includeAllModules to maybe reduce confusion.

Maybe it would also make sense to include some additional pointers of how to go about it - or some type of flag to ignore if it's just for local use in the manpage.

Otoh, in general it seems to me like It greatly reduces usefulness if one would have to go and fix upstream modules from repos like home-manager, just to have the options being shown in the manpage.

What do you think?

[domenkozar]

I agree about the error.

[edolstra]

This change causes a giant options.xml.drv file to be generated (#83863). Aside from that, this fix seems wrong since options.xml shouldn't depend on derivations to begin with! After all, it can things to be built that wouldn't otherwise be built. (This is why we have literalExample, BTW.)

[domenkozar]

+1 and add a comment.

[jtojnar]

Reverted in 513cec9 and cab6b01, backported to 20.03 in 9412ae3. Verified that jobsets now evaluate.

[worldofpeace]

@edolstra This was an issue for me in cc94d5e.