treewide: remove lib.mdDoc

[stuebinm]

Motivation

lib.mdDoc has been a no-op (i.e., been defined as mdDoc = id) since the completion of the docs migration and the removal of Docbook about ten months ago. Nevertheless, it is still used in many, many places, and it seems unrealistic to remove it from each module one-by-one (tracking issue on this).

Description of changes

This removes all uses of lib.mdDoc anywhere in nixpkgs. As was discussed in the docs matrix channel, it also replaces mdDoc's definition with a call to lib.warn giving a hint to downstream module authors that they should likewise remove its use.

The string mdDoc remains in nixpkgs in only four cases: its own definition, once as a literal string in the nixos-render-docs python script (where it can probably be removed as well, but I'm not familiar enough with it to make changes there), and twice in commented-out nix code.

The manuals built before and after this change are identical (according to diffoscope the only change is a store path referencing the module directory, where change is unavoidable if we change the nix source files).

Implementation details

As with #297084 I generated these changes via my own rnix-based rust utility, which is syntax-aware enough to both find actual use-sites & hopefully smart enough to remove then-redundant parens and whitespace, leaving the actual nix code in (i think) a reasonably clean-looking state.

I've also split this up into several commits (one each for changing nixos, lib, and pkgs/top-level/config.nix, and a final one for changing mdDoc's definition) in hopes of making it at least slightly less unwieldy to review.

(note for reviewers: re-generating these changes takes only a few seconds, so please don't worry about this branch going out-of-sync with master quickly; if need be, I can regenerate the same changes on a more current master before merging)

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/)
• 24.05 Release Notes (or backporting 23.05 and 23.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
• Fits CONTRIBUTING.md.

[philiptaron]

@stuebinm this is fantastic, and thanks for nixq also.

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/nix-darwin-is-broken/43497/2

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/nix-darwin-is-broken/43497/3

[jjpe]

Unfortunately this PR breaks nix-darwin.
It seems there are packages there that have not yet had the requisite maintenance.

[mweinelt]

If this broke nix-darwin, then they need to remove their usage of lib.mdDoc, that should be all.

[jjpe]

True that may be, but I ran into this as someone relatively new to Nix-the-language.
As such, I unfortunately have no experience fixing this kind of issue just yet.
Which means all I can do at this time is draw attention to it, and hope that someone who does have the required knowledge will fix it.

[roberth]

If this broke nix-darwin, then they need to remove their usage of lib.mdDoc, that should be all.

We try to have a friendly deprecation cycle in lib so that this kind of thing is at most a warning that can be ignored by users and acted on by maintainers.
Unfortunately, this PR was merged hastily, understandably.
Solution in

• lib: add mdDoc back in to provide proper warning; set explicit timeline for removal #304277

[jonringer]

Yes, was most concerned that the scope of this PR would cause it to go into "conflict limbo".

Removal of the lib.mdDoc entry was on me, should be an eval warning, not a hard "mdDoc could not be found" error.

Edit: thank you @eclairevoyant for the fix

[RaitoBezarius]

For the next urgent merge, note that OP wrote:

(note for reviewers: re-generating these changes takes only a few seconds, so please don't worry about this branch going out-of-sync with master quickly; if need be, I can regenerate the same changes on a more current master before merging)

Using a codemod tool, there's no hurry to regenerate those changes, which makes those treewides possible to discuss without going too fast.

Thank you @eclairevoyant for the fix.

[jonringer]

Maybe having treewide re-writes and deprecations be separate PRs should be the norm in the future. One has a lot of bulk changes but little implications out-of-tree, and the other does not have many changes but many implications out-of-tree.