lib.neovimConfiguration: deprecated extraModules and configuration (#377)

* lib.neovimConfiguration: deprecated extraModules and configuration

* docs: various fixes

.github/workflows/manual.yml

@@ -1,4 +1,5 @@
 name: "Build and deploy documentation"
+
 on:
   workflow_dispatch:
   push:
@@ -7,6 +8,7 @@ on:
     paths:
       # build the manuals only when docs directory is updated
       - docs/**
+      - modules/**
 
 # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:
@@ -20,23 +22,34 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  check_date:
+    runs-on: ubuntu-latest
+    name: Check latest commit
+    outputs:
+      should_run: ${{ steps.should_run.outputs.should_run }}
+    steps:
+      - uses: actions/checkout@v4.1.7
+      - name: print latest_commit
+        run: echo ${{ github.sha }}
+
+      - id: should_run
+        continue-on-error: true
+        name: check latest commit is less than a day
+        if: ${{ github.event_name == 'schedule' }}
+        run: test -z $(git rev-list --after="24 hours" ${{ github.sha }}) && echo "::set-output name=should_run::false"
+
   publish:
+    needs: check_date
+    if: ${{ needs.check_date.outputs.should_run != 'false' }}
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Install Nix
-        uses: DeterminateSystems/nix-installer-action@main
+      - uses: actions/checkout@v4.1.7
+      - uses: DeterminateSystems/nix-installer-action@main
       - uses: DeterminateSystems/magic-nix-cache-action@main
-
-      - name: Build
-        run: |
-          nix build '.#docs'
+      - run: |
+          nix build .#docs
           cp -r result/share/doc/nvf public
-
-      - name: Deploy
-        uses: peaceiris/actions-gh-pages@v4
+      - uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./public

docs/default.nix

@@ -2,131 +2,135 @@
   inputs,
   pkgs,
   lib,
-  manpageUrls ? pkgs.path + "/doc/manpage-urls.json",
-  ...
 }: let
-  inherit (lib.modules) mkForce evalModules;
-  inherit (lib.strings) hasPrefix removePrefix;
-  inherit (lib.attrsets) isAttrs mapAttrs optionalAttrs recursiveUpdate isDerivation;
-  inherit (builtins) fromJSON readFile;
+  inherit ((lib.importJSON ../release.json)) release;
 
-  # release data
-  release-config = fromJSON (readFile ../release.json);
-  revision = release-config.release;
-
-  # From home-manager:
-  #
-  # Recursively replace each derivation in the given attribute set
-  # with the same derivation but with the `outPath` attribute set to
-  # the string `"\${pkgs.attribute.path}"`. This allows the
-  # documentation to refer to derivations through their values without
-  # establishing an actual dependency on the derivation output.
-  #
-  # This is not perfect, but it seems to cover a vast majority of use
-  # cases.
-  #
-  # Caveat: even if the package is reached by a different means, the
-  # path above will be shown and not e.g.
-  # `${config.services.foo.package}`.
-  scrubDerivations = prefixPath: attrs: let
-    scrubDerivation = name: value: let
-      pkgAttrName = prefixPath + "." + name;
-    in
-      if isAttrs value
-      then
-        scrubDerivations pkgAttrName value
-        // optionalAttrs (isDerivation value) {
-          outPath = "\${${pkgAttrName}}";
-        }
-      else value;
-  in
-    mapAttrs scrubDerivation attrs;
-
-  # Make sure the used package is scrubbed to avoid actually
-  # instantiating derivations.
-  scrubbedPkgsModule = {
-    imports = [
-      {
-        _module.args = {
-          pkgs = mkForce (scrubDerivations "pkgs" pkgs);
-          pkgs_i686 = mkForce {};
-        };
-      }
-    ];
-  };
-
-  # Specify the path to the module entrypoint
-  nvimPath = toString ./..;
-  buildOptionsDocs = args @ {
-    modules,
-    includeModuleSystemOptions ? true,
-    warningsAreErrors ? true,
-    ...
-  }: let
-    inherit ((evalModules {inherit modules;})) options;
-
-    # Declaration of the Github site URL.
-    # Takes a user, repo, and subpath, and returns a declaration site
-    # as a string.
-    githubDeclaration = user: repo: subpath: let
-      urlRef = "github.com";
-      branch = "main";
-    in {
-      url = "https://${urlRef}/${user}/${repo}/blob/${branch}/${subpath}";
-      name = "<${repo}/${subpath}>";
-    };
-  in
-    pkgs.buildPackages.nixosOptionsDoc ({
-        inherit warningsAreErrors;
-
-        options =
-          if includeModuleSystemOptions
-          then options
-          else builtins.removeAttrs options ["_module"];
-
-        transformOptions = opt:
-          recursiveUpdate opt {
-            # Clean up declaration sites to not refer to the nvf
-            # source tree.
-            declarations = map (decl:
-              if hasPrefix nvimPath (toString decl)
-              then
-                githubDeclaration "notashelf" "nvf"
-                (removePrefix "/" (removePrefix nvimPath (toString decl)))
-              else if decl == "lib/modules.nix"
-              then
-                # TODO: handle this in a better way (may require upstream
-                # changes to nixpkgs)
-                githubDeclaration "NixOS" "nixpkgs" decl
-              else decl)
-            opt.declarations;
-          };
-      }
-      // builtins.removeAttrs args ["modules" "includeModuleSystemOptions"]);
-
-  nvimModuleDocs = buildOptionsDocs {
+  nvimModuleDocs = pkgs.nixosOptionsDoc {
     variablelistId = "nvf-options";
+    warningsAreErrors = true;
 
-    modules =
-      import ../modules/modules.nix {
-        inherit lib pkgs;
-        check = false;
-      }
-      ++ [scrubbedPkgsModule];
+    inherit
+      (
+        (lib.evalModules {
+          modules =
+            import ../modules/modules.nix {
+              inherit lib pkgs;
+            }
+            ++ [
+              (
+                let
+                  # From nixpkgs:
+                  #
+                  # Recursively replace each derivation in the given attribute set
+                  # with the same derivation but with the `outPath` attribute set to
+                  # the string `"\${pkgs.attribute.path}"`. This allows the
+                  # documentation to refer to derivations through their values without
+                  # establishing an actual dependency on the derivation output.
+                  #
+                  # This is not perfect, but it seems to cover a vast majority of use
+                  # cases.
+                  #
+                  # Caveat: even if the package is reached by a different means, the
+                  # path above will be shown and not e.g.
+                  # `${config.services.foo.package}`.
+                  scrubDerivations = namePrefix: pkgSet:
+                    builtins.mapAttrs (
+                      name: value: let
+                        wholeName = "${namePrefix}.${name}";
+                      in
+                        if builtins.isAttrs value
+                        then
+                          scrubDerivations wholeName value
+                          // lib.optionalAttrs (lib.isDerivation value) {
+                            inherit (value) drvPath;
+                            outPath = "\${${wholeName}}";
+                          }
+                        else value
+                    )
+                    pkgSet;
+                in {
+                  _module = {
+                    check = false;
+                    args.pkgs = lib.mkForce (scrubDerivations "pkgs" pkgs);
+                  };
+                }
+              )
+            ];
+        })
+      )
+      options
+      ;
+
+    transformOptions = opt:
+      opt
+      // {
+        declarations =
+          map (
+            decl:
+              if lib.hasPrefix (toString ../.) (toString decl)
+              then
+                lib.pipe decl [
+                  toString
+                  (lib.removePrefix (toString ../.))
+                  (lib.removePrefix "/")
+                  (x: {
+                    url = "https://github.com/NotAShelf/nvf/blob/main/${decl}";
+                    name = "<nvf/${x}>";
+                  })
+                ]
+              else if decl == "lib/modules.nix"
+              then {
+                url = "https://github.com/NixOS/nixpkgs/blob/master/${decl}";
+                name = "<nixpkgs/lib/modules.nix>";
+              }
+              else decl
+          )
+          opt.declarations;
+      };
   };
 
+  # Generate the HTML manual pages
+  html = pkgs.callPackage ./manual.nix {
+    inherit release;
+    inherit (nvimModuleDocs) optionsJSON;
+  };
+in {
+  inherit (inputs) nmd;
+
+  # TODO: Use `hmOptionsDocs.optionsJSON` directly once upstream
+  # `nixosOptionsDoc` is more customizable.
+  options.json =
+    pkgs.runCommand "options.json"
+    {
+      meta.description = "List of nvf options in JSON format";
+    }
+    ''
+      mkdir -p $out/{share/doc,nix-support}
+      cp -a ${nvimModuleDocs.optionsJSON}/share/doc/nixos $out/share/doc/nvf
+      substitute \
+        ${nvimModuleDocs.optionsJSON}/nix-support/hydra-build-products \
+        $out/nix-support/hydra-build-products \
+        --replace \
+        '${nvimModuleDocs.optionsJSON}/share/doc/nixos' \
+        "$out/share/doc/nvf"
+    '';
+
   # Generate the `man home-configuration.nix` package
-  nvf-configuration-manual =
-    pkgs.runCommand "nvf-reference-manpage" {
-      nativeBuildInputs = [pkgs.buildPackages.installShellFiles pkgs.nixos-render-docs];
+  manPages =
+    pkgs.runCommand "nvf-reference-manpage"
+    {
+      nativeBuildInputs = [
+        pkgs.buildPackages.installShellFiles
+        pkgs.nixos-render-docs
+      ];
       allowedReferences = ["out"];
-    } ''
+    }
+    ''
       # Generate manpages.
-      mkdir -p $out/share/man/man5
-      mkdir -p $out/share/man/man1
+      mkdir -p $out/share/man/{man5,man1}
 
       nixos-render-docs -j $NIX_BUILD_CORES options manpage \
-        --revision ${revision} \
+        --revision ${release} \
         --header ${./man/header.5} \
         --footer ${./man/footer.5} \
         ${nvimModuleDocs.optionsJSON}/share/doc/nixos/options.json \
@@ -135,38 +139,8 @@
       cp ${./man/nvf.1} $out/share/man/man1/nvf.1
     '';
 
-  # Generate the HTML manual pages
-  nvf-manual = pkgs.callPackage ./manual.nix {
-    inherit revision manpageUrls;
-    outputPath = "share/doc/nvf";
-    options = {
-      nvf = nvimModuleDocs.optionsJSON;
-    };
+  manual = {
+    inherit html;
+    htmlOpenTool = pkgs.callPackage ./html-open-tool.nix {inherit html;};
   };
-
-  html = nvf-manual;
-  htmlOpenTool = pkgs.callPackage ./html-open-tool.nix {} {inherit html;};
-in {
-  inherit (inputs) nmd;
-
-  options = {
-    # TODO: Use `hmOptionsDocs.optionsJSON` directly once upstream
-    # `nixosOptionsDoc` is more customizable.
-    json =
-      pkgs.runCommand "options.json" {
-        meta.description = "List of nvf options in JSON format";
-      } ''
-        mkdir -p $out/{share/doc,nix-support}
-        cp -a ${nvimModuleDocs.optionsJSON}/share/doc/nixos $out/share/doc/nvf
-        substitute \
-          ${nvimModuleDocs.optionsJSON}/nix-support/hydra-build-products \
-          $out/nix-support/hydra-build-products \
-          --replace \
-            '${nvimModuleDocs.optionsJSON}/share/doc/nixos' \
-            "$out/share/doc/nvf"
-      '';
-  };
-
-  manPages = nvf-configuration-manual;
-  manual = {inherit html htmlOpenTool;};
 }

docs/html-open-tool.nix

@@ -2,13 +2,9 @@
   writeShellScriptBin,
   makeDesktopItem,
   symlinkJoin,
-}: {
   html,
-  pathName ? "nvf",
-  projectName ? pathName,
-  name ? "${pathName}-help",
 }: let
-  helpScript = writeShellScriptBin name ''
+  helpScript = writeShellScriptBin "nvf-help" ''
     set -euo pipefail
 
     if [[ ! -v BROWSER || -z $BROWSER ]]; then
@@ -24,20 +20,23 @@
       echo "$0: unable to start a web browser; please set \$BROWSER"
       exit 1
     else
-      exec "$BROWSER" "${html}/share/doc/${pathName}/index.xhtml"
+      exec "$BROWSER" "${html}/share/doc/nvf/index.xhtml"
     fi
   '';
 
   desktopItem = makeDesktopItem {
-    name = "${pathName}-manual";
-    desktopName = "${projectName} Manual";
-    genericName = "View ${projectName} documentation in a web browser";
+    name = "nvf-manual";
+    desktopName = "nvf Manual";
+    genericName = "View nvf documentation in a web browser";
     icon = "nix-snowflake";
-    exec = "${helpScript}/bin/${name}";
+    exec = "${helpScript}/bin/nvf-help";
     categories = ["System"];
   };
 in
   symlinkJoin {
-    inherit name;
-    paths = [helpScript desktopItem];
+    name = "nvf-help";
+    paths = [
+      helpScript
+      desktopItem
+    ];
   }

docs/manual.nix

@@ -4,11 +4,10 @@
   # build inputs
   nixos-render-docs,
   documentation-highlighter,
+  path,
   # nrd configuration
-  manpageUrls,
-  revision,
-  options,
-  outputPath ? "share/doc/nvf",
+  release,
+  optionsJSON,
 }:
 stdenvNoCC.mkDerivation {
   name = "nvf-manual";
@@ -20,9 +19,11 @@ stdenvNoCC.mkDerivation {
   nativeBuildInputs = [nixos-render-docs];
 
   buildPhase = ''
-    mkdir -p out/{highlightjs,media}
+    dest="$out/share/doc/nvf"
+    mkdir -p "$(dirname "$dest")"
+    mkdir -p $dest/{highlightjs,media}
 
-    cp -vt out/highlightjs \
+    cp -vt $dest/highlightjs \
       ${documentation-highlighter}/highlight.pack.js \
       ${documentation-highlighter}/LICENSE \
       ${documentation-highlighter}/mono-blue.css \
@@ -31,38 +32,32 @@ stdenvNoCC.mkDerivation {
     substituteInPlace ./options.md \
       --subst-var-by \
         OPTIONS_JSON \
-        ${options.nvf}/share/doc/nixos/options.json
+        ${optionsJSON}/share/doc/nixos/options.json
 
     substituteInPlace ./manual.md \
       --subst-var-by \
         NVF_VERSION \
-        ${revision}
+        ${release}
 
     # copy stylesheet
-    cp ${./static/style.css} out/style.css
+    cp ${./static/style.css} "$dest/style.css"
 
     # copy release notes
     cp -vr ${./release-notes} release-notes
 
     # generate manual from
     nixos-render-docs manual html \
-      --manpage-urls ${manpageUrls} \
-      --revision ${lib.trivial.revisionWithDefault revision} \
+      --manpage-urls ${path + "/doc/manpage-urls.json"} \
+      --revision ${lib.trivial.revisionWithDefault release} \
       --stylesheet style.css \
       --script highlightjs/highlight.pack.js \
       --script highlightjs/loader.js \
       --toc-depth 2 \
       --section-toc-depth 1 \
       manual.md \
-      out/index.xhtml
-  '';
+      "$dest/index.xhtml"
 
-  installPhase = ''
-    dest="$out/${outputPath}"
-    mkdir -p "$(dirname "$dest")"
-    mv out "$dest"
-
-    mkdir -p $out/nix-support/
-    echo "doc manual $dest index.html" >> $out/nix-support/hydra-build-products
+      mkdir -p $out/nix-support/
+      echo "doc manual $dest index.html" >> $out/nix-support/hydra-build-products
   '';
 }

flake/packages.nix

@@ -8,6 +8,7 @@
     docs = import ../docs {inherit pkgs inputs lib;};
   in {
     packages = {
+      inherit (docs.manual) htmlOpenTool;
       # Documentation
       docs = docs.manual.html;
       docs-html = docs.manual.html;

lib/configuration.nix

@@ -1,18 +0,0 @@
-{
-  inputs,
-  lib,
-}: let
-  modulesWithInputs = import ../modules inputs;
-in
-  {
-    modules ? [],
-    pkgs,
-    check ? true,
-    extraSpecialArgs ? {},
-    extraModules ? [],
-    ...
-  }:
-    modulesWithInputs {
-      inherit pkgs lib check extraSpecialArgs extraModules;
-      configuration.imports = modules;
-    }

lib/default.nix

@@ -11,5 +11,5 @@
   languages = import ./languages.nix {inherit lib;};
   lists = import ./lists.nix {inherit lib;};
   lua = import ./lua.nix {inherit lib;};
-  neovimConfiguration = import ./configuration.nix {inherit inputs lib;};
+  neovimConfiguration = import ../modules {inherit inputs lib;};
 }

modules/default.nix

@@ -1,10 +1,13 @@
-inputs: {
-  configuration,
-  pkgs,
+{
+  inputs,
   lib,
-  check ? true,
+}: {
+  pkgs,
   extraSpecialArgs ? {},
+  modules ? [],
+  # deprecated
   extraModules ? [],
+  configuration ? {},
 }: let
   inherit (pkgs) vimPlugins;
   inherit (lib.strings) isString toString;
@@ -13,13 +16,25 @@ inputs: {
   # import modules.nix with `check`, `pkgs` and `lib` as arguments
   # check can be disabled while calling this file is called
   # to avoid checking in all modules
-  nvimModules = import ./modules.nix {inherit pkgs check lib;};
+  nvimModules = import ./modules.nix {inherit pkgs lib;};
 
   # evaluate the extended library with the modules
   # optionally with any additional modules passed by the user
   module = lib.evalModules {
     specialArgs = extraSpecialArgs // {modulesPath = toString ./.;};
-    modules = concatLists [[configuration] nvimModules extraModules];
+    modules = concatLists [
+      nvimModules
+      modules
+      (lib.optional (configuration != {}) (lib.warn ''
+          nvf: passing 'configuration' to lib.neovimConfiguration is deprecated.
+        ''
+        configuration))
+
+      (lib.optionals (extraModules != []) (lib.warn ''
+          nvf: passing 'extraModules' to lib.neovimConfiguration is deprecated, use 'modules' instead.
+        ''
+        extraModules))
+    ];
   };
 
   # alias to the internal configuration

modules/modules.nix

@@ -1,77 +1,72 @@
 {
-  check ? true,
   pkgs,
   lib,
 }: let
   inherit (lib.modules) mkDefault;
   inherit (lib.lists) concatLists;
+  allModules = let
+    # The core neovim modules.
+    # Contains configuration for core neovim features
+    # such as spellchecking, mappings, and the init script (init.vim).
+    neovim = map (p: "${./neovim}/${p}") [
+      "init"
+      "mappings"
+    ];
 
-  # The core neovim modules.
-  # Contains configuration for core neovim features
-  # such as spellchecking, mappings, and the init script (init.vim).
-  neovim = map (p: ./neovim + "/${p}") [
-    "init"
-    "mappings"
-  ];
+    # Individual plugin modules, separated by the type of plugin.
+    # While adding a new type, you must make sure your type is
+    # included in the list below.
+    plugins = map (p: "${./plugins}/${p}") [
+      "assistant"
+      "autopairs"
+      "comments"
+      "completion"
+      "dashboard"
+      "debugger"
+      "filetree"
+      "git"
+      "languages"
+      "lsp"
+      "minimap"
+      "notes"
+      "projects"
+      "rich-presence"
+      "session"
+      "snippets"
+      # "spellcheck" # FIXME: see neovim/init/spellcheck.nix
+      "statusline"
+      "tabline"
+      "terminal"
+      "theme"
+      "treesitter"
+      "ui"
+      "utility"
+      "visuals"
+    ];
 
-  # Individual plugin modules, separated by the type of plugin.
-  # While adding a new type, you must make sure your type is
-  # included in the list below.
-  plugins = map (p: ./plugins + "/${p}") [
-    "assistant"
-    "autopairs"
-    "comments"
-    "completion"
-    "dashboard"
-    "debugger"
-    "filetree"
-    "git"
-    "languages"
-    "lsp"
-    "minimap"
-    "notes"
-    "projects"
-    "rich-presence"
-    "session"
-    "snippets"
-    # "spellcheck" # FIXME: see neovim/init/spellcheck.nix
-    "statusline"
-    "tabline"
-    "terminal"
-    "theme"
-    "treesitter"
-    "ui"
-    "utility"
-    "visuals"
-  ];
+    # The neovim wrapper, used to build a wrapped neovim package
+    # using the configuration passed in `neovim` and `plugins` modules.
+    wrapper = map (p: "${./wrapper}/${p}") [
+      "build"
+      "rc"
+      "warnings"
+    ];
 
-  # The neovim wrapper, used to build a wrapped neovim package
-  # using the configuration passed in `neovim` and `plugins` modules.
-  wrapper = map (p: ./wrapper + "/${p}") [
-    "build"
-    "rc"
-    "warnings"
-  ];
-
-  # Extra modules, such as deprecation warnings
-  # or renames in one place.
-  extra = map (p: ./extra + "/${p}") [
-    "deprecations.nix"
-  ];
-
-  allModules = concatLists [neovim plugins wrapper extra];
-
-  pkgsModule = {config, ...}: {
-    config = {
-      _module = {
-        inherit check;
-        args = {
-          baseModules = allModules;
-          pkgsPath = mkDefault pkgs.path;
-          pkgs = mkDefault pkgs;
-        };
-      };
-    };
-  };
+    # Extra modules, such as deprecation warnings
+    # or renames in one place.
+    extra = map (p: "${./extra}/${p}") [
+      "deprecations.nix"
+    ];
+  in
+    concatLists [neovim plugins wrapper extra];
 in
-  allModules ++ [pkgsModule]
+  allModules
+  ++ [
+    {
+      _module.args = {
+        baseModules = allModules;
+        pkgsPath = mkDefault pkgs.path;
+        pkgs = mkDefault pkgs;
+      };
+    }
+  ]