From 57be605ed411c1de4a9fa0b1951aa31f56fbde18 Mon Sep 17 00:00:00 2001 From: Gerg-L <88247690+Gerg-L@users.noreply.github.com> Date: Sun, 22 Sep 2024 19:52:10 +0000 Subject: [PATCH] lib.neovimConfiguration: deprecated extraModules and configuration (#377) * lib.neovimConfiguration: deprecated extraModules and configuration * docs: various fixes --- .github/workflows/manual.yml | 37 +++-- docs/default.nix | 268 ++++++++++++++++------------------- docs/html-open-tool.nix | 23 ++- docs/manual.nix | 35 ++--- flake/packages.nix | 1 + lib/configuration.nix | 18 --- lib/default.nix | 2 +- modules/default.nix | 27 +++- modules/modules.nix | 129 ++++++++--------- 9 files changed, 257 insertions(+), 283 deletions(-) delete mode 100644 lib/configuration.nix diff --git a/.github/workflows/manual.yml b/.github/workflows/manual.yml index 34c11ff..23381e4 100644 --- a/.github/workflows/manual.yml +++ b/.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 diff --git a/docs/default.nix b/docs/default.nix index b48daf5..4a9d2f8 100644 --- a/docs/default.nix +++ b/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 = ""; + }) + ] + else if decl == "lib/modules.nix" + then { + url = "https://github.com/NixOS/nixpkgs/blob/master/${decl}"; + name = ""; + } + 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;}; } diff --git a/docs/html-open-tool.nix b/docs/html-open-tool.nix index 756feba..d430d24 100644 --- a/docs/html-open-tool.nix +++ b/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 + ]; } diff --git a/docs/manual.nix b/docs/manual.nix index 14e8ae2..f5b23d0 100644 --- a/docs/manual.nix +++ b/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 ''; } diff --git a/flake/packages.nix b/flake/packages.nix index f8ad3c2..84514a2 100644 --- a/flake/packages.nix +++ b/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; diff --git a/lib/configuration.nix b/lib/configuration.nix deleted file mode 100644 index 1f3c59a..0000000 --- a/lib/configuration.nix +++ /dev/null @@ -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; - } diff --git a/lib/default.nix b/lib/default.nix index 2e4b7f8..a418cff 100644 --- a/lib/default.nix +++ b/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;}; } diff --git a/modules/default.nix b/modules/default.nix index 1ae3b03..6a95080 100644 --- a/modules/default.nix +++ b/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 diff --git a/modules/modules.nix b/modules/modules.nix index a00cea6..195652d 100644 --- a/modules/modules.nix +++ b/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; + }; + } + ]