Use of deferredModule leads to incomplete documentation

[roberth]

Describe the bug

A deferred module is one that is yet to be made part of an actual configuration (ie submodule or evalModules).
While it is possible to specify statically known modules in deferredModuleWith, for the purpose of adding documentation, this is only feasible when such a module is also meant to be part of the actual deferred module value.
It is not currently possible to specify a module solely for the purpose of documentation, without affecting usages of the module.

Steps To Reproduce

Design a module system application that relies on the user specifying a deferred module U.
This deferred module will be combined with "hardcoded" options in module H provided by the module system application.
However, U is also exposed as a flake attribute.
As a consequence, it may be loaded in a different version of the module system application, which adds a compatible but not identical module H2.
A configuration with U, H and H2 will be evaluated. H and H2 are not deduplicated because they exist at distinct file system paths, yet they declare the same options. This evaluation will fail with an error about conflicting options in H and H2.
Loading module H was not desired, so it should not have been added to staticModules.
We now lose the generated documentation for H (and H2 for that matter).

Workarounds

• Use example, description on the option to describe the expected options.
  • This gets messy for large sets of options
• Generate a separate page for these options and link to it.
  • This could be a bit surprising and tends to require some ad hoc build code

Proposed behavior

Maybe add documentationModules parameter, used for documentation, just like staticModules, but only for documentation and not for actual, normal evaluation.

Additional context

• Option docs haskellProjects.<name>.packages is incomplete srid/haskell-flake#272

Notify maintainers

@roberth @infinisil

Metadata

Please run nix-shell -p nix-info --run "nix-info -m" and paste the result.

[user@system:~]$ nix-shell -p nix-info --run "nix-info -m"
output here

---

Add a 👍 reaction to issues you find important.