lib.neovimConfiguration: deprecated extraModules and configuration (#377)
Some checks failed
Set up binary cache / cachix (default) (push) Has been cancelled
Set up binary cache / cachix (maximal) (push) Has been cancelled
Set up binary cache / cachix (nix) (push) Has been cancelled
Validate flake & check documentation / Validate Flake Documentation (docs) (push) Has been cancelled
Validate flake & check documentation / Validate Flake Documentation (docs-html) (push) Has been cancelled
Validate flake & check documentation / Validate Flake Documentation (docs-json) (push) Has been cancelled
Validate flake & check documentation / Validate Flake Documentation (docs-manpages) (push) Has been cancelled
Validate flake & check formatting / Validate Flake (push) Has been cancelled
Validate flake & check formatting / Formatting via Alejandra (push) Has been cancelled
Build and deploy documentation / Check latest commit (push) Has been cancelled
Build and deploy documentation / publish (push) Has been cancelled

* lib.neovimConfiguration: deprecated extraModules and configuration

* docs: various fixes
This commit is contained in:
Gerg-L 2024-09-22 19:52:10 +00:00 committed by GitHub
parent 99ace503ad
commit 57be605ed4
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
9 changed files with 257 additions and 283 deletions

View file

@ -1,4 +1,5 @@
name: "Build and deploy documentation" name: "Build and deploy documentation"
on: on:
workflow_dispatch: workflow_dispatch:
push: push:
@ -7,6 +8,7 @@ on:
paths: paths:
# build the manuals only when docs directory is updated # build the manuals only when docs directory is updated
- docs/** - docs/**
- modules/**
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions: permissions:
@ -20,23 +22,34 @@ concurrency:
cancel-in-progress: true cancel-in-progress: true
jobs: 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: publish:
needs: check_date
if: ${{ needs.check_date.outputs.should_run != 'false' }}
runs-on: ubuntu-latest runs-on: ubuntu-latest
steps: steps:
- name: Checkout - uses: actions/checkout@v4.1.7
uses: actions/checkout@v4 - uses: DeterminateSystems/nix-installer-action@main
- name: Install Nix
uses: DeterminateSystems/nix-installer-action@main
- uses: DeterminateSystems/magic-nix-cache-action@main - uses: DeterminateSystems/magic-nix-cache-action@main
- run: |
- name: Build nix build .#docs
run: |
nix build '.#docs'
cp -r result/share/doc/nvf public cp -r result/share/doc/nvf public
- uses: peaceiris/actions-gh-pages@v4
- name: Deploy
uses: peaceiris/actions-gh-pages@v4
with: with:
github_token: ${{ secrets.GITHUB_TOKEN }} github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./public publish_dir: ./public

View file

@ -2,131 +2,135 @@
inputs, inputs,
pkgs, pkgs,
lib, lib,
manpageUrls ? pkgs.path + "/doc/manpage-urls.json",
...
}: let }: let
inherit (lib.modules) mkForce evalModules; inherit ((lib.importJSON ../release.json)) release;
inherit (lib.strings) hasPrefix removePrefix;
inherit (lib.attrsets) isAttrs mapAttrs optionalAttrs recursiveUpdate isDerivation;
inherit (builtins) fromJSON readFile;
# release data nvimModuleDocs = pkgs.nixosOptionsDoc {
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 {
variablelistId = "nvf-options"; variablelistId = "nvf-options";
warningsAreErrors = true;
modules = inherit
import ../modules/modules.nix { (
inherit lib pkgs; (lib.evalModules {
check = false; modules =
} import ../modules/modules.nix {
++ [scrubbedPkgsModule]; 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 # Generate the `man home-configuration.nix` package
nvf-configuration-manual = manPages =
pkgs.runCommand "nvf-reference-manpage" { pkgs.runCommand "nvf-reference-manpage"
nativeBuildInputs = [pkgs.buildPackages.installShellFiles pkgs.nixos-render-docs]; {
nativeBuildInputs = [
pkgs.buildPackages.installShellFiles
pkgs.nixos-render-docs
];
allowedReferences = ["out"]; allowedReferences = ["out"];
} '' }
''
# Generate manpages. # Generate manpages.
mkdir -p $out/share/man/man5 mkdir -p $out/share/man/{man5,man1}
mkdir -p $out/share/man/man1
nixos-render-docs -j $NIX_BUILD_CORES options manpage \ nixos-render-docs -j $NIX_BUILD_CORES options manpage \
--revision ${revision} \ --revision ${release} \
--header ${./man/header.5} \ --header ${./man/header.5} \
--footer ${./man/footer.5} \ --footer ${./man/footer.5} \
${nvimModuleDocs.optionsJSON}/share/doc/nixos/options.json \ ${nvimModuleDocs.optionsJSON}/share/doc/nixos/options.json \
@ -135,38 +139,8 @@
cp ${./man/nvf.1} $out/share/man/man1/nvf.1 cp ${./man/nvf.1} $out/share/man/man1/nvf.1
''; '';
# Generate the HTML manual pages manual = {
nvf-manual = pkgs.callPackage ./manual.nix { inherit html;
inherit revision manpageUrls; htmlOpenTool = pkgs.callPackage ./html-open-tool.nix {inherit html;};
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"
'';
};
manPages = nvf-configuration-manual;
manual = {inherit html htmlOpenTool;};
} }

View file

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

View file

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

View file

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

View file

@ -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;
}

View file

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

View file

@ -1,10 +1,13 @@
inputs: { {
configuration, inputs,
pkgs,
lib, lib,
check ? true, }: {
pkgs,
extraSpecialArgs ? {}, extraSpecialArgs ? {},
modules ? [],
# deprecated
extraModules ? [], extraModules ? [],
configuration ? {},
}: let }: let
inherit (pkgs) vimPlugins; inherit (pkgs) vimPlugins;
inherit (lib.strings) isString toString; inherit (lib.strings) isString toString;
@ -13,13 +16,25 @@ inputs: {
# import modules.nix with `check`, `pkgs` and `lib` as arguments # import modules.nix with `check`, `pkgs` and `lib` as arguments
# check can be disabled while calling this file is called # check can be disabled while calling this file is called
# to avoid checking in all modules # 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 # evaluate the extended library with the modules
# optionally with any additional modules passed by the user # optionally with any additional modules passed by the user
module = lib.evalModules { module = lib.evalModules {
specialArgs = extraSpecialArgs // {modulesPath = toString ./.;}; 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 # alias to the internal configuration

View file

@ -1,77 +1,72 @@
{ {
check ? true,
pkgs, pkgs,
lib, lib,
}: let }: let
inherit (lib.modules) mkDefault; inherit (lib.modules) mkDefault;
inherit (lib.lists) concatLists; 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. # Individual plugin modules, separated by the type of plugin.
# Contains configuration for core neovim features # While adding a new type, you must make sure your type is
# such as spellchecking, mappings, and the init script (init.vim). # included in the list below.
neovim = map (p: ./neovim + "/${p}") [ plugins = map (p: "${./plugins}/${p}") [
"init" "assistant"
"mappings" "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. # The neovim wrapper, used to build a wrapped neovim package
# While adding a new type, you must make sure your type is # using the configuration passed in `neovim` and `plugins` modules.
# included in the list below. wrapper = map (p: "${./wrapper}/${p}") [
plugins = map (p: ./plugins + "/${p}") [ "build"
"assistant" "rc"
"autopairs" "warnings"
"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 # Extra modules, such as deprecation warnings
# using the configuration passed in `neovim` and `plugins` modules. # or renames in one place.
wrapper = map (p: ./wrapper + "/${p}") [ extra = map (p: "${./extra}/${p}") [
"build" "deprecations.nix"
"rc" ];
"warnings" in
]; concatLists [neovim plugins wrapper extra];
# 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;
};
};
};
};
in in
allModules ++ [pkgsModule] allModules
++ [
{
_module.args = {
baseModules = allModules;
pkgsPath = mkDefault pkgs.path;
pkgs = mkDefault pkgs;
};
}
]