diff --git a/docs/helpers.md b/docs/helpers.md new file mode 100644 index 00000000..9a2cc3ce --- /dev/null +++ b/docs/helpers.md @@ -0,0 +1,39 @@ +# Helpers + +Regardless of the way NixVim is used (as a home-manager module, a nixos module, or as a standalone module), +helpers can be included in the same way. + +You can simply use: + +```nix +{ + helpers, + ... +}: { + # Your config +} +``` + +A certain number of helpers are defined that can be useful: + +- `helpers.emptyTable`: An empty lua table `{}` that will be included in the final lua configuration. + This is equivalent to `{__empty = {};}`. This form can allow to do `option.__empty = {}`. + +- `helpers.mkRaw str`: Write the string `str` as raw lua in the final lua configuration. + This is equivalent to `{__raw = "lua code";}`. This form can allow to do `option.__raw = "lua code"`. + +- `helpers.toLuaObject obj`: Create a string representation of the Nix object. Useful to define your own plugins. + +- `helpers.listToUnkeyedAttrs list`: Transforms a list to an "unkeyed" attribute set. + + This allows to define mixed table/list in lua: + + ```nix + (listToUnkeyedAttrs ["a", "b"]) // {foo = "bar";} + ``` + + Resulting in the following lua: + + ```lua + {"a", "b", [foo] = "bar"} + ``` diff --git a/docs/man/default.nix b/docs/man/default.nix index 84b7eeac..1c665747 100644 --- a/docs/man/default.nix +++ b/docs/man/default.nix @@ -3,17 +3,45 @@ runCommand, installShellFiles, nixos-render-docs, -}: -runCommand "nixvim-configuration-reference-manpage" { - nativeBuildInputs = [installShellFiles nixos-render-docs]; -} '' - # Generate man-pages - mkdir -p $out/share/man/man5 - nixos-render-docs -j $NIX_BUILD_CORES options manpage \ - --revision unstable \ - --header ${./nixvim-header.5} \ - --footer ${./nixvim-footer.5} \ - ${options-json}/share/doc/nixos/options.json \ - $out/share/man/man5/nixvim.5 - compressManPages $out -'' + pandoc, +}: let + capitalizeHeaders = '' + local text = pandoc.text + + function Header(el) + if el.level == 1 then + return el:walk { + Str = function(el) + return pandoc.Str(text.upper(el.text)) + end + } + end + end + ''; + + manHeader = + runCommand "nixvim-general-doc-manpage" { + nativeBuildInputs = [pandoc]; + inherit capitalizeHeaders; + } '' + mkdir -p $out + cat \ + ${./nixvim-header-start.5} \ + <(pandoc --lua-filter <(echo "$capitalizeHeaders") -f gfm -t man ${../helpers.md}) \ + ${./nixvim-header-end.5} \ + >$out/nixvim-header.5 + ''; +in + runCommand "nixvim-configuration-reference-manpage" { + nativeBuildInputs = [installShellFiles nixos-render-docs]; + } '' + # Generate man-pages + mkdir -p $out/share/man/man5 + nixos-render-docs -j $NIX_BUILD_CORES options manpage \ + --revision unstable \ + --header ${manHeader}/nixvim-header.5 \ + --footer ${./nixvim-footer.5} \ + ${options-json}/share/doc/nixos/options.json \ + $out/share/man/man5/nixvim.5 + compressManPages $out + '' diff --git a/docs/man/nixvim-header-end.5 b/docs/man/nixvim-header-end.5 new file mode 100644 index 00000000..d8b26530 --- /dev/null +++ b/docs/man/nixvim-header-end.5 @@ -0,0 +1,3 @@ +.SH "OPTIONS" +.PP +You can use the following options in a NixVim module. diff --git a/docs/man/nixvim-header.5 b/docs/man/nixvim-header-start.5 similarity index 87% rename from docs/man/nixvim-header.5 rename to docs/man/nixvim-header-start.5 index 5988313c..c95aac78 100644 --- a/docs/man/nixvim-header.5 +++ b/docs/man/nixvim-header-start.5 @@ -10,6 +10,3 @@ NixVim options specification .SH "DESCRIPTION" .PP This page lists all the options that can be used in NixVim. It can either be used as a Home-Manager module, an NixOS module or a standalone package. Please refer to the installation instructions for more details. -.SH "OPTIONS" -.PP -You can use the following options in a NixVim module. diff --git a/docs/mdbook/SUMMARY.md b/docs/mdbook/SUMMARY.md index bd0c8628..3f4911e8 100644 --- a/docs/mdbook/SUMMARY.md +++ b/docs/mdbook/SUMMARY.md @@ -9,3 +9,4 @@ --- [Contributing](./CONTRIBUTING.md) +[Helpers](./helpers.md) diff --git a/docs/mdbook/default.nix b/docs/mdbook/default.nix index 7ebb1853..9fd48853 100644 --- a/docs/mdbook/default.nix +++ b/docs/mdbook/default.nix @@ -217,6 +217,7 @@ with lib; let # Copy inputs into the build directory cp -r --no-preserve=all $inputs/* ./ cp ${../../CONTRIBUTING.md} ./CONTRIBUTING.md + cp ${../helpers.md} ./helpers.md # Copy the generated MD docs into the build directory # Using pkgs.writeShellScript helps to avoid the "bash: argument list too long" error