docs: Add a short sections on helpers (#1093)

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"}
+  ```

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
+  ''

docs/man/nixvim-header-end.5

@@ -0,0 +1,3 @@
+.SH "OPTIONS"
+.PP
+You can use the following options in a NixVim module.

docs/man/nixvim-header.5 → 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.

docs/mdbook/SUMMARY.md

@@ -9,3 +9,4 @@
 ---
 
 [Contributing](./CONTRIBUTING.md)
+[Helpers](./helpers.md)

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