lib: support alternative type names

[deemp]

Describe the bug

I can't set descriptive names for submodule-s and see these names in docs.

Steps To Reproduce

• Build docs

  nix build github:deemp/nix2workflows/f9294924c7a0d071579bee5af881059aa2208932#example.x86_64-linux.internal.config.modules-docs.markdown -o result.md
  

• Open result.md

• See there null or (submodule)

• See there workflows.<name>

Expected behavior

I can set a descriptive type name and path segment name in the code and get that name in the docs.

Additional context

Currently, in submoduleWith, a name isn't a parameter (link) and it's used in a couple of places (1, 2, 3).

The submoduleWith is used inside the definition of submoduleWith (1, 2). Hence, it's hard to correctly override name in all places.

The "submoduleWith" string occurs in erros inside submoduleWith (link).

Additionally, I see the "submodule" string is used:

• in modules.nix

  nixpkgs/lib/modules.nix

  Line 650 in af105fd

  if all (x: x.options.type.name or null == "submodule") optionDecls

• in a nixos-option.cc

  nixpkgs/pkgs/tools/nix/nixos-option/nixos-option.cc

  Line 274 in af105fd

  if (isOption(ctx, v) && optionTypeIs(ctx, v, "submodule")) {

Possible solution

• Add a stableName attribute to option types.
  • The stableName is a stable type name.
  • The name is a pretty type name.
  • The name should default to stableName.

Notify maintainers

@infinisil
@roberth

Metadata

[user@system:~]$ nix run nixpkgs#nix-info -- -m
 - system: `"x86_64-linux"`
 - host os: `Linux 6.2.0-39-generic, Ubuntu, 22.04.4 LTS (Jammy Jellyfish), nobuild`
 - multi-user?: `no`
 - sandbox: `yes`
 - version: `nix-env (Nix) 2.19.4`
 - nixpkgs: `not found`

---

Add a 👍 reaction to issues you find important.

[infinisil]

I believe submoduleWith's description should do what you want:

diff --git a/nix/common.nix b/nix/common.nix
index 39b27d4..f7cbe83 100644
--- a/nix/common.nix
+++ b/nix/common.nix
@@ -75,7 +75,10 @@ rec {
             mkSubmoduleOption =
               options:
               lib.mkOption {
-                type = lib.types.nullOr (lib.types.submodule { inherit options; });
+                type = lib.types.nullOr (lib.types.submoduleWith {
+                  description = "My type";
+                  modules = [ { inherit options; } ];
+                });
                 default = null;
               };

=>

#### `workflows.<name>.on.branch_protection_rule`

**Type**:

```text
null or (My type)
```

[deemp]

@infinisil, indeed, thank you!

For some reason, in the original issue, I provided the context for another question.

How do I override the name in workflows.<name>?

[infinisil]

Ah looks like #295872 then, to which I just replied with a suggestion :)

[roberth]

Would class be a suitable name to use in the type description?
We'd automatically have descriptions like:

• nixos module
• nixosTest module
• nixpkgsConfig module

and whichever classes may exist in the wild.

[deemp]

@roberth, I think my issue is resolved for now. Please reopen if you think it can be worked on.