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,19 +2,24 @@
   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;
+  nvimModuleDocs = pkgs.nixosOptionsDoc {
+    variablelistId = "nvf-options";
+    warningsAreErrors = true;
 
-  # From home-manager:
+    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
@@ -28,134 +33,78 @@
                   # 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;
+                  scrubDerivations = namePrefix: pkgSet:
+                    builtins.mapAttrs (
+                      name: value: let
+                        wholeName = "${namePrefix}.${name}";
                       in
-      if isAttrs value
+                        if builtins.isAttrs value
                         then
-        scrubDerivations pkgAttrName value
-        // optionalAttrs (isDerivation value) {
-          outPath = "\${${pkgAttrName}}";
+                          scrubDerivations wholeName value
+                          // lib.optionalAttrs (lib.isDerivation value) {
+                            inherit (value) drvPath;
+                            outPath = "\${${wholeName}}";
                           }
-      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";
+                        else value
+                    )
+                    pkgSet;
                 in {
-      url = "https://${urlRef}/${user}/${repo}/blob/${branch}/${subpath}";
-      name = "<${repo}/${subpath}>";
+                  _module = {
+                    check = false;
+                    args.pkgs = lib.mkForce (scrubDerivations "pkgs" pkgs);
                   };
-  in
-    pkgs.buildPackages.nixosOptionsDoc ({
-        inherit warningsAreErrors;
-
-        options =
-          if includeModuleSystemOptions
-          then options
-          else builtins.removeAttrs options ["_module"];
+                }
+              )
+            ];
+        })
+      )
+      options
+      ;
 
     transformOptions = opt:
-          recursiveUpdate opt {
-            # Clean up declaration sites to not refer to the nvf
-            # source tree.
-            declarations = map (decl:
-              if hasPrefix nvimPath (toString decl)
+      opt
+      // {
+        declarations =
+          map (
+            decl:
+              if lib.hasPrefix (toString ../.) (toString decl)
               then
-                githubDeclaration "notashelf" "nvf"
-                (removePrefix "/" (removePrefix nvimPath (toString decl)))
+                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
-                # TODO: handle this in a better way (may require upstream
-                # changes to nixpkgs)
-                githubDeclaration "NixOS" "nixpkgs" decl
-              else decl)
+              then {
+                url = "https://github.com/NixOS/nixpkgs/blob/master/${decl}";
+                name = "<nixpkgs/lib/modules.nix>";
+              }
+              else decl
+          )
           opt.declarations;
       };
-      }
-      // builtins.removeAttrs args ["modules" "includeModuleSystemOptions"]);
-
-  nvimModuleDocs = buildOptionsDocs {
-    variablelistId = "nvf-options";
-
-    modules =
-      import ../modules/modules.nix {
-        inherit lib pkgs;
-        check = false;
-      }
-      ++ [scrubbedPkgsModule];
   };
 
-  # Generate the `man home-configuration.nix` package
-  nvf-configuration-manual =
-    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
-
-      nixos-render-docs -j $NIX_BUILD_CORES options manpage \
-        --revision ${revision} \
-        --header ${./man/header.5} \
-        --footer ${./man/footer.5} \
-        ${nvimModuleDocs.optionsJSON}/share/doc/nixos/options.json \
-        $out/share/man/man5/nvf.5
-
-      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;
+  html = pkgs.callPackage ./manual.nix {
+    inherit release;
+    inherit (nvimModuleDocs) optionsJSON;
   };
-  };
-
-  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" {
+  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 \
@@ -165,8 +114,33 @@ in {
         '${nvimModuleDocs.optionsJSON}/share/doc/nixos' \
         "$out/share/doc/nvf"
     '';
-  };
 
-  manPages = nvf-configuration-manual;
-  manual = {inherit html htmlOpenTool;};
+  # Generate the `man home-configuration.nix` package
+  manPages =
+    pkgs.runCommand "nvf-reference-manpage"
+    {
+      nativeBuildInputs = [
+        pkgs.buildPackages.installShellFiles
+        pkgs.nixos-render-docs
+      ];
+      allowedReferences = ["out"];
+    }
+    ''
+      # Generate manpages.
+      mkdir -p $out/share/man/{man5,man1}
+
+      nixos-render-docs -j $NIX_BUILD_CORES options manpage \
+        --revision ${release} \
+        --header ${./man/header.5} \
+        --footer ${./man/footer.5} \
+        ${nvimModuleDocs.optionsJSON}/share/doc/nixos/options.json \
+        $out/share/man/man5/nvf.5
+
+      cp ${./man/nvf.1} $out/share/man/man1/nvf.1
+    '';
+
+  manual = {
+    inherit html;
+    htmlOpenTool = pkgs.callPackage ./html-open-tool.nix {inherit html;};
+  };
 }

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,36 +32,30 @@ 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
-  '';
-
-  installPhase = ''
-    dest="$out/${outputPath}"
-    mkdir -p "$(dirname "$dest")"
-    mv out "$dest"
+      "$dest/index.xhtml"
 
       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,15 +1,14 @@
 {
-  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}") [
+    neovim = map (p: "${./neovim}/${p}") [
       "init"
       "mappings"
     ];
@@ -17,7 +16,7 @@
     # 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}") [
+    plugins = map (p: "${./plugins}/${p}") [
       "assistant"
       "autopairs"
       "comments"
@@ -47,7 +46,7 @@
 
     # The neovim wrapper, used to build a wrapped neovim package
     # using the configuration passed in `neovim` and `plugins` modules.
-  wrapper = map (p: ./wrapper + "/${p}") [
+    wrapper = map (p: "${./wrapper}/${p}") [
       "build"
       "rc"
       "warnings"
@@ -55,23 +54,19 @@
 
     # Extra modules, such as deprecation warnings
     # or renames in one place.
-  extra = map (p: ./extra + "/${p}") [
+    extra = map (p: "${./extra}/${p}") [
       "deprecations.nix"
     ];
-
-  allModules = concatLists [neovim plugins wrapper extra];
-
-  pkgsModule = {config, ...}: {
-    config = {
-      _module = {
-        inherit check;
-        args = {
+  in
+    concatLists [neovim plugins wrapper extra];
+in
+  allModules
+  ++ [
+    {
+      _module.args = {
         baseModules = allModules;
         pkgsPath = mkDefault pkgs.path;
         pkgs = mkDefault pkgs;
       };
-      };
-    };
-  };
-in
-  allModules ++ [pkgsModule]
+    }
+  ]