Better handling of title/example in options

Author: thomasjm

OPTIONS.md

@@ -33,12 +33,13 @@
         '';
 
         optionsDoc = pkgsMaster.nixosOptionsDoc {
-          options = ((pkgsMaster.callPackage ./nix/evaluate-config.nix {
+          # Fold each option's "title" into its description so it survives into the docs.
+          options = (import ./nix/fold-option-titles.nix { lib = pkgsMaster.lib; }) (((pkgsMaster.callPackage ./nix/evaluate-config.nix {
             inherit pkgsStable pkgsMaster;
             extraSpecialArgs = {
               pkgs = {};
             };
-          }) {}).options;
+          }) {}).options);
           transformOptions = opt: opt // {
             # Remove declarations to hide "Declared by" lines
             declarations = [];

flake.nix

@@ -5,14 +5,23 @@ with lib;
 {
   options = {
     environment.variables = mkOption {
+      title = "Environment variables";
       type = types.attrsOf types.str;
       default = {};
       description = "Environment variables to set.";
     };
 
     environment.extraNix = mkOption {
+      title = "Extra Nix";
       type = types.codeMirrorLines "nix";
       default = "";
+      example = ''
+        with pkgs;
+        symlinkJoin {
+          name = "extra-packages";
+          paths = [ hello cowsay ];
+        }
+      '';
       description = "Arbitrary Nix expression that evaluates to a derivation, which will be joined into the environment. The expression has \"pkgs\" in scope, an imported Nixpkgs package set.";
     };
   };

modules/environment/module.nix

@@ -7,7 +7,7 @@ with lib;
     exporters.nbconvert = {
       enable = mkOption {
         type = types.bool;
-        example = "Enable nbconvert exporters";
+        title = "Enable nbconvert exporters";
         description = "Enable the nbconvert exporters.";
         default = false;
         visible = false;
@@ -36,7 +36,7 @@ with lib;
           "scheme-full"
         ];
         default = "scheme-full";
-        example = "TeX Live scheme";
+        title = "TeX Live scheme";
         description = "The TeX Live scheme to use, as an attribute of pkgs.texlive.combined.*";
       };
     };

modules/exporters/nbconvert/module.nix

@@ -7,7 +7,7 @@ with lib;
     exporters.pandoc = {
       enable = mkOption {
         type = types.bool;
-        example = "Enable pandoc exporters";
+        title = "Enable pandoc exporters";
         description = "Enable the pandoc exporters.";
         default = false;
         visible = false;
@@ -36,7 +36,7 @@ with lib;
           "scheme-full"
         ];
         default = "scheme-full";
-        example = "TeX Live scheme";
+        title = "TeX Live scheme";
         description = "The TeX Live scheme to use, as an attribute of pkgs.texlive.combined.*";
       };
     };

modules/exporters/pandoc/module.nix

@@ -16,10 +16,13 @@ let
 
   common = callPackage ../../kernels/common.nix {};
 
+  # Also writes a dependency file at "<output>.deps" (typst's native JSON
+  # {"inputs": [...]}, paths relative to cwd) so the runner can watch imported
+  # files and re-render when any of them changes. See exporterInfoDeps below.
   script = common.writeShellScriptBinWithAttrs {} "typst-export" ''
     echo_and_run() { echo "$*" ; "$@" ; }
     echo_and_run export PATH="''${PATH:+''${PATH}:}"
-    echo_and_run ${typst}/bin/typst compile "$1" "$2"
+    echo_and_run ${typst}/bin/typst compile --deps "$2.deps" "$1" "$2"
   '';
 
   typstToUse = typst.withPackages (ps: (map (x: ps.${x}) packages));
@@ -43,6 +46,7 @@ let
     args = [(script + "/bin/typst-export")];
     input_extensions = ["typ"];
     pandoc = "${pandoc}/bin/pandoc";
+    deps = "typst_json";
   };
 
 in

modules/exporters/typst/default.nix

@@ -10,7 +10,7 @@ let
         type = types.str;
       };
       outputs = mkOption {
-        example = "Package outputs to include";
+        title = "Package outputs to include";
         type = types.listOf types.str;
       };
     };
@@ -23,34 +23,34 @@ in
     exporters.typst = {
       enable = mkOption {
         type = types.bool;
-        example = "Enable Typst exporter";
+        title = "Enable Typst exporter";
         description = "Enable the Typst exporters.";
         default = false;
         visible = false;
       };
 
       packages = mkOption {
-        example = "List of packages";
+        title = "List of packages";
         type = types.listOf (types.either types.str subPackage);
         default = [];
         visible = false;
       };
 
       interface.attrs = mkOption {
-        example = boilerplate.attrsTitle;
+        title = boilerplate.attrsTitle;
         description = boilerplate.attrsDescription;
         type = types.listOf types.str;
         default = ["typst"];
       };
       interface.extensions = mkOption {
-        example = boilerplate.extensionsTitle;
+        title = boilerplate.extensionsTitle;
         description = boilerplate.extensionsDescription;
         type = types.listOf types.str;
         default = ["typ"];
       };
 
       lsp.tinymist.enable = mkOption {
-        example = "Enable tinymist language server";
+        title = "Enable tinymist language server";
         type = types.bool;
         default = true;
       };

modules/exporters/typst/module.nix

@@ -11,27 +11,27 @@ in
   options = {
     kernels.bash = {
       enable = mkOption {
-        example = "Enable Bash kernel";
+        title = "Enable Bash kernel";
         type = types.bool;
         default = false;
         visible = false;
       };
 
       interface.attrs = mkOption {
-        example = boilerplate.attrsTitle;
+        title = boilerplate.attrsTitle;
         description = boilerplate.attrsDescription;
         type = types.listOf types.str;
         default = ["bash"];
       };
       interface.extensions = mkOption {
-        example = boilerplate.extensionsTitle;
+        title = boilerplate.extensionsTitle;
         description = boilerplate.extensionsDescription;
         type = types.listOf types.str;
         default = ["sh" "bash"];
       };
 
       lsp.bash-language-server.enable = mkOption {
-        example = "Enable Bash language server";
+        title = "Enable Bash language server";
         type = types.bool;
         default = true;
       };

modules/kernels/bash/module.nix

@@ -6,27 +6,27 @@ with lib;
   options = {
     kernels.clojure = {
       enable = mkOption {
-        example = "Enable Clojure kernel";
+        title = "Enable Clojure kernel";
         type = types.bool;
         default = false;
         visible = false;
       };
 
       interface.attrs = mkOption {
-        example = boilerplate.attrsTitle;
+        title = boilerplate.attrsTitle;
         description = boilerplate.attrsDescription;
         type = types.listOf types.str;
         default = ["clojure"];
       };
       interface.extensions = mkOption {
-        example = boilerplate.extensionsTitle;
+        title = boilerplate.extensionsTitle;
         description = boilerplate.extensionsDescription;
         type = types.listOf types.str;
         default = ["clj"];
       };
 
       lsp.clojure-lsp.enable = mkOption {
-        example = "Enable clojure-lsp language server";
+        title = "Enable clojure-lsp language server";
         type = types.bool;
         default = true;
       };

modules/kernels/clojure/module.nix

@@ -11,21 +11,21 @@ in
   options = {
     kernels.coq = {
       enable = mkOption {
-        example = "Enable Coq kernel";
+        title = "Enable Coq kernel";
         type = types.bool;
         default = false;
         visible = false;
       };
 
       packages = mkOption {
-        example = "List of Coq packages to use";
+        title = "List of Coq packages to use";
         type = types.listOf types.str;
         default = [];
         visible = false;
       };
 
       coqPackages = mkOption {
-        example = "Coq packages set";
+        title = "Coq packages set";
         type = types.enum (
           ["coqPackages"]
           ++ (builtins.filter (name: builtins.substring 0 (builtins.stringLength "coqPackages_") name == "coqPackages_")
@@ -35,13 +35,13 @@ in
       };
 
       interface.attrs = mkOption {
-        example = boilerplate.attrsTitle;
+        title = boilerplate.attrsTitle;
         description = boilerplate.attrsDescription;
         type = types.listOf types.str;
         default = ["coq"];
       };
       interface.extensions = mkOption {
-        example = boilerplate.extensionsTitle;
+        title = boilerplate.extensionsTitle;
         description = boilerplate.extensionsDescription;
         type = types.listOf types.str;
         default = ["v"];