Bug | Option Documents Break Nix Build

[ReedClanton]

Description

Two issue existed with the options documentation that caused build failures when documentation.nixos.enable and documentation.nixos.includeAllModules are set to true.

The first issue was that mkDoc was used rather than lib.mdDoc in two locations. mkDoc isn't valid, so I replaced both instances of it with lib.mdDoc.

The second issue was that not all options of nix-flatpak had descriptions. This also causes a build failure.

In addition to fixing the two issues above that cause build failures, I also:

• Fixed a typo in README.md.
• Made minor additions and corrections to existing option docs.
• Added spaces so option docs would be rendered correctly:
  • The way multi-line string blocks work in Nix is that the indent is determined by the line that's indented the least.
  • Thus all lines should be indented the same, even blank lines.

Why Wasn't it Noticed Sooner

By default documentation.nixos.enable is true and documentation.nixos.includeAllModules is false. The latter value used to default to true, but was changed due to build performance concerns for NixOps users. Having said that, there has been discussion of turning the default back to true for non NixOps users. If this is done, then everyone who uses this module will end up with broken system builds.

In short, I noticed first because I was the first person to use this module and set documentation.nixos.includeAllModules to true.

[gmodena]

Hey @ReedClanton. Thanks for this.

Could be a leftover of some early experiments with doc generation.
Annoying that it was only caught at runtime.

[gmodena]

I have not been able to reproduce (all my dev/testing systems build with documentation.nixos.includeAllModules=true).

Regardless, I like that you streamlined documentation functions. Will merge.

[ReedClanton]

I have not been able to reproduce (all my dev/testing systems build with documentation.nixos.includeAllModules=true).

That's baffling. I can reproduce it on 3 machines. Given they all use the same base configuration.