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:
-  publish:
+  check_date:
     runs-on: ubuntu-latest
+    name: Check latest commit
+    outputs:
+      should_run: ${{ steps.should_run.outputs.should_run }}
     steps:
-      - name: Checkout
-        uses: actions/checkout@v4
+      - uses: actions/[email protected]
+      - name: print latest_commit
+        run: echo ${{ github.sha }}
 
-      - name: Install Nix
-        uses: DeterminateSystems/nix-installer-action@main
-      - uses: DeterminateSystems/magic-nix-cache-action@main
+      - 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"
 
-      - name: Build
-        run: |
-          nix build '.#docs'
+  publish:
+    needs: check_date
+    if: ${{ needs.check_date.outputs.should_run != 'false' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/[email protected]
+      - uses: DeterminateSystems/nix-installer-action@main
+      - uses: DeterminateSystems/magic-nix-cache-action@main
+      - 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)
+  nvimModuleDocs = pkgs.nixosOptionsDoc {
+    variablelistId = "nvf-options";
+    warningsAreErrors = true;
+
+    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
-                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)
-            opt.declarations;
-          };
-      }
-      // builtins.removeAttrs args ["modules" "includeModuleSystemOptions"]);
-
-  nvimModuleDocs = buildOptionsDocs {
-    variablelistId = "nvf-options";
+              then {
+                url = "https://github.com/NixOS/nixpkgs/blob/master/${decl}";
+                name = "<nixpkgs/lib/modules.nix>";
+              }
+              else decl
+          )
+          opt.declarations;
+      };
+  };
 
-    modules =
-      import ../modules/modules.nix {
-        inherit lib pkgs;
-        check = false;
-      }
-      ++ [scrubbedPkgsModule];
+  # 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;
-    };
-  };
-
-  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"
-      '';
+  manual = {
+    inherit html;
+    htmlOpenTool = pkgs.callPackage ./html-open-tool.nix {inherit html;};
   };
-
-  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
+    ];
   }