fix: docs expressions

Author: deemp

modules/modules-docs.nix

@@ -114,11 +114,17 @@ let
       )
   );
 
+  inherit (import ../nix/commands/lib.nix { inherit pkgs; }) mkLocLast nestedOptionsType;
+
   # TODO: display values like TOML instead.
   toMarkdown = optionsDocs:
     let
-      optionsDocsPartitioned = partition (opt: (take 2 opt.loc) == [ "commands" "<name>" ]) optionsDocs;
+      nixOnlyLocPrefix = [ "commands" "<name>" ];
+      optionsDocsPartitioned = partition (opt: (take 2 opt.loc) == nixOnlyLocPrefix) optionsDocs;
       nixOnly = optionsDocsPartitioned.right;
+      nixOnlyTopPartitioned = partition (opt: opt.loc == nixOnlyLocPrefix ++ [ "*" ]) nixOnly;
+      nixOnlyPartitioned = partition (opt: ("${last opt.loc}" == "${mkLocLast nestedOptionsType.name}")) nixOnlyTopPartitioned.wrong;
+      nixOnly_ = nixOnlyTopPartitioned.right ++ nixOnlyPartitioned.right ++ nixOnlyPartitioned.wrong;
       nixTOML = filter (opt: head opt.loc != "_module") optionsDocsPartitioned.wrong;
 
       # TODO: handle opt.relatedPackages. What is it for?
@@ -168,7 +174,7 @@ let
       doc = [
         "# `devshell` options\n"
         "## Available only in `Nix`\n"
-        (concatStringsSep "\n" (map optToMd nixOnly))
+        (concatStringsSep "\n" (map optToMd nixOnly_))
         "## Available in `Nix` and `TOML`\n"
         (concatStringsSep "\n" (map optToMd nixTOML))
       ];

nix/commands/flatOptions.nix

@@ -1,4 +1,4 @@
-{ lib, strOrPackage }:
+{ lib, strOrPackage, flatOptionsType }:
 with lib;
 # These are all the options available for the commands.
 {
@@ -14,16 +14,20 @@ with lib;
     type = types.nullOr types.str;
     default = null;
     description = ''
-      Name of this command. Defaults to attribute name in commands.
+      Name of this command. 
+      
+      Defaults to a `(${flatOptionsType.name}) package` name or pname if present.
+
+      The value of this option is required for a `(${flatOptionsType.name}) command`.
     '';
   };
 
   category = mkOption {
     type = types.str;
     default = "[general commands]";
     description = ''
-      Set a free text category under which this command is grouped
-      and shown in the help menu.
+      Sets a free text category under which this command is grouped
+      and shown in the devshell menu.
     '';
   };
 
@@ -64,7 +68,7 @@ with lib;
     type = types.bool;
     default = true;
     description = ''
-      When `true`, the `command` or the `package` will be added to the environment.
+      When `true`, the `(${flatOptionsType.name}) command` or the `(${flatOptionsType.name}) package` will be added to the environment.
         
       Otherwise, they will not be added to the environment, but will be printed
       in the devshell description.

nix/commands/nestedOptions.nix

@@ -1,11 +1,19 @@
-{ pkgs, strOrPackage, attrsNestedOf, pairHelpPackageType, pairHelpCommandType, flatOptionsType, maxDepth }:
+{ pkgs
+, strOrPackage
+, attrsNestedOf
+, pairHelpPackageType
+, pairHelpCommandType
+, flatOptionsType
+, nestedOptionsType
+, maxDepth
+}:
 with pkgs.lib;
 {
   prefix = mkOption {
     type = types.nullOr types.str;
     default = "";
     description = ''
-      Possible `${flatOptionsType.name}.prefix`.
+      Possible `(${flatOptionsType.name}) prefix`.
       
       Priority of this option when selecting a prefix: `1`.
       
@@ -22,7 +30,7 @@ with pkgs.lib;
     type = types.nullOr (attrsNestedOf types.str);
     default = { };
     description = ''
-      A leaf value becomes a `${flatOptionsType.name}.prefix`
+      A leaf value becomes a `(${flatOptionsType.name}) prefix`
       of a `package` (`command`) with a matching path in `packages` (`commands`).
 
       Priority of this option when selecting a prefix: `2`.
@@ -46,37 +54,38 @@ with pkgs.lib;
         ]));
     default = { };
     description = ''
-      A nested (max depth is ${toString maxDepth}) attrset of `${flatOptionsType.name}.package`-s
+      A nested (max depth is ${toString maxDepth}) attrset of `(${flatOptionsType.name}) package`-s
       to describe in the devshell menu
       and optionally bring to the environment.
 
       A path to a leaf value is concatenated via `.`
-      and used as a suffix of `${flatOptionsType.name}.name`.
+      and used as a `(${flatOptionsType.name}) name`.
 
       A leaf value can be of three types.
         
       1. When a `string` with a value `<string>`,
          devshell tries to resolve a derivation
-         `pkgs.<string>` and use it as a `${flatOptionsType.name}.package`.
+         `pkgs.<string>` and use it as a `(${flatOptionsType.name}) package`.
 
-      2. When a `derivation`, it's used as a `${flatOptionsType.name}.package`.
+      2. When a `derivation`, it's used as a `(${flatOptionsType.name}) package`.
 
       3. When a list with two elements:
          1. The first element is a `string`
-            that is used to select a `${flatOptionsType.name}.help`.
-            - Priority of this `string` (if present) when selecting a `${flatOptionsType.name}.help`: `4`.
+            that is used to select a `(${flatOptionsType.name}) help`.
+            - Priority of this `string` (if present) when selecting a `(${flatOptionsType.name}) help`: `4`.
 
               Lowest priority: `1`.
          2. The second element is interpreted as if
             the leaf value were initially a `string` or a `derivation`.
         
-      Priority of `package.meta.description` (if present in the resolved `${flatOptionsType.name}.package`) when selecting a `${flatOptionsType.name}.help`: 2
+      Priority of `package.meta.description` (if present in the resolved `(${flatOptionsType.name}) package`) 
+      when selecting a `(${flatOptionsType.name}) help`: 2
       
       Lowest priority: `1`.
 
       A user may prefer not to bring the environment some of the packages.
       
-      Priority of `expose = false` when selecting a `${flatOptionsType.name}.expose`: `1`.
+      Priority of `expose = false` when selecting a `(${flatOptionsType.name}) expose`: `1`.
       
       Lowest priority: `1`.
     '';
@@ -96,33 +105,33 @@ with pkgs.lib;
         ]));
     default = { };
     description = ''
-      A nested (max depth is ${toString maxDepth}) attrset of `${flatOptionsType.name}.command`-s
+      A nested (max depth is ${toString maxDepth}) attrset of `(${flatOptionsType.name}) command`-s
       to describe in the devshell menu
       and bring to the environment.
 
       A path to a leaf value is concatenated via `.`
-      and used in the `${flatOptionsType.name}.name`.
+      and used in the `(${flatOptionsType.name}) name`.
 
       A leaf value can be of two types.
         
-      1. When a `string`, it's used as a `${flatOptionsType.name}.command`.
+      1. When a `string`, it's used as a `(${flatOptionsType.name}) command`.
 
       2. When a list with two elements:
          1. the first element of type `string` with a value `<string>`
             that is used to select a `help`;
 
-            Priority of the `<string>` (if present) when selecting a `${flatOptionsType.name}.help`: `4`
+            Priority of the `<string>` (if present) when selecting a `(${flatOptionsType.name}) help`: `4`
 
             Lowest priority: `1`.
-         1. the second element of type `string` is used as a `command`.
+         1. the second element of type `string` is used as a `(${flatOptionsType.name}) command`.
     '';
   };
 
   help = mkOption {
     type = types.nullOr types.str;
-    default = "no help message provided :(";
+    default = "";
     description = ''
-      Priority of this option when selecting a `${flatOptionsType.name}.help`: `1`.
+      Priority of this option when selecting a `(${flatOptionsType.name}) help`: `1`.
       
       Lowest priority: `1`.
     '';
@@ -137,9 +146,11 @@ with pkgs.lib;
     type = types.nullOr (attrsNestedOf types.str);
     default = { };
     description = ''
-      A leaf value can be used as `${flatOptionsType.name}.help` for a `package` (`command`) with a matching path in `packages` (`commands`).
+      A leaf value can be used as `(${flatOptionsType.name}) help`
+      for a `(${flatOptionsType.name}) package` (`(${flatOptionsType.name}) command`) 
+      with a matching path in `(${nestedOptionsType.name}) packages` (`(${nestedOptionsType.name}) commands`).
 
-      Priority of this option when selecting a `${flatOptionsType.name}.help`: `3`.
+      Priority of this option when selecting a `(${flatOptionsType.name}) help`: `3`.
       
       Lowest priority: `1`.
     '';
@@ -160,7 +171,7 @@ with pkgs.lib;
       Otherwise, they can not be added to the environment,
       but will be printed in the devshell description.
       
-      Priority of this option when selecting a `${flatOptionsType.name}.expose`: `2`.
+      Priority of this option when selecting a `(${flatOptionsType.name}) expose`: `2`.
       
       Lowest priority: `1`.
     '';
@@ -175,11 +186,13 @@ with pkgs.lib;
     type = types.nullOr (attrsNestedOf types.bool);
     default = { };
     description = ''
-      A nested (max depth is ${toString maxDepth}) attrset of `${flatOptionsType.name}.expose`-s.
+      A nested (max depth is ${toString maxDepth}) attrset of `(${flatOptionsType.name}) expose`-s.
       
-      A leaf value can be used as `${flatOptionsType.name}.expose` for a `package` (`command`) with a matching path in `packages` (`commands`).
+      A leaf value can be used as `(${flatOptionsType.name}) expose` 
+      for a `(${flatOptionsType.name}) package` (`(${flatOptionsType.name}) command`)
+      with a matching path in `(${nestedOptionsType.name}) packages` (`(${nestedOptionsType.name}) commands`).
 
-      Priority of this option when selecting a `${flatOptionsType.name}.expose`: `3`.
+      Priority of this option when selecting a `(${flatOptionsType.name}) expose`: `3`.
       
       Lowest priority: `1`.
     '';

nix/commands/types.nix

@@ -37,10 +37,12 @@ rec {
     merge = mergeOneOption;
   };
 
-  flatOptions = import ./flatOptions.nix { inherit lib strOrPackage; };
+  flatOptions = import ./flatOptions.nix { inherit lib strOrPackage flatOptionsType; };
 
   mkAttrsToString = str: { __toString = _: str; };
 
+  mkLocLast = name: mkAttrsToString " (${name})";
+
   flatOptionsType =
     let submodule = types.submodule { options = flatOptions; }; in
     submodule // rec {
@@ -50,7 +52,7 @@ rec {
         (name_: value: value // {
           loc = prefix ++ [
             name_
-            (mkAttrsToString " (${name})")
+            (mkLocLast name)
           ];
           declarations = [ "${toString ../..}/nix/commands/flatOptions.nix" ];
         })
@@ -61,7 +63,12 @@ rec {
 
   pairHelpCommandType = list2Of types.str types.str;
 
-  nestedOptions = import ./nestedOptions.nix { inherit pkgs strOrPackage attrsNestedOf pairHelpPackageType pairHelpCommandType flatOptionsType maxDepth; };
+  nestedOptions = import ./nestedOptions.nix {
+    inherit
+      pkgs strOrPackage attrsNestedOf pairHelpPackageType
+      pairHelpCommandType flatOptionsType maxDepth
+      nestedOptionsType;
+  };
 
   nestedOptionsType =
     let submodule = types.submodule { options = nestedOptions; }; in
@@ -146,7 +153,7 @@ rec {
         mkOption {
           type = nestedConfigType;
           description = ''
-            A config for command(s) when the `commands` option is an attrset ("nested").
+            A config for command(s) when the `commands` option is an attrset.
           '';
           example = literalExpression ''
             {