docs: New documentation using mdbook (nix-community#471)

* docs: mdbook init

* Separate sub-options into their section

* docs: enable fold

* docs: merge core options into a single section

* doc generation: fix submodules index pages

* docs: add contributing section

* docs: rename 'core' group to 'Neovim Options'

docs: removed the index pages of empty sections

docs: remove obsolete 'mergeFunctionResults' function

* docs: use nix syntax highlighting

* docs: point to the new repo url

* docs: use recursive generation
docs: split submodules into subsections

* docs: fix contributing separator
docs: fix missing submodules docs

docs/SUMMARY.md

@@ -0,0 +1,11 @@
+# Structure for nixvim docs 
+
+# Options
+
+@NIXVIM_OPTIONS@
+
+#
+
+---
+
+[Contributing](./CONTRIBUTING.md)

docs/book.toml

@@ -0,0 +1,10 @@
+[book]
+authors = []
+language = "en"
+multilingual = false
+src = "."
+title = "nixvim docs"
+
+[output.html.fold]
+enable = true
+level = 0

docs/default.nix

@@ -0,0 +1,235 @@
+{
+  pkgs,
+  lib,
+  modules,
+  ...
+}:
+with lib; let
+  options = lib.evalModules {
+    inherit modules;
+    specialArgs = {inherit pkgs lib;};
+  };
+
+  mkMDDoc = options:
+    (pkgs.nixosOptionsDoc {
+      options = filterAttrs (k: _: k != "_module") options;
+      warningsAreErrors = false;
+      transformOptions = opts:
+        opts
+        // {
+          declarations = with builtins;
+            map
+            (
+              decl:
+                if hasPrefix "/nix/store/" decl
+                then let
+                  filepath = toString (match "^/nix/store/[^/]*/(.*)" decl);
+                in {
+                  url = "https://github.com/nix-community/nixvim/blob/main/${filepath}";
+                  name = filepath;
+                }
+                else decl
+            )
+            opts.declarations;
+        };
+    })
+    .optionsCommonMark;
+
+  removeUnwanted = attrs:
+    builtins.removeAttrs attrs [
+      "_module"
+      "_freeformOptions"
+      "warnings"
+      "assertions"
+      "content"
+    ];
+
+  removeWhitespace = builtins.replaceStrings [" "] [""];
+
+  getSubOptions = opts: path: removeUnwanted (opts.type.getSubOptions path);
+
+  wrapModule = path: opts: isOpt: rec {
+    index = {
+      options =
+        if isOpt
+        then opts
+        else filterAttrs (_: component: component.isOption) opts;
+      path = concatStringsSep "/" path;
+    };
+
+    components =
+      if isOpt
+      then {}
+      else filterAttrs (_: component: !component.isOption) opts;
+
+    hasComponents = components != {};
+
+    isOption = isOpt;
+  };
+
+  processModulesRec = modules: let
+    recurse = path: mods: let
+      g = name: opts:
+        if !isOption opts
+        then wrapModule (path ++ [name]) (recurse (path ++ [name]) opts) false
+        else let
+          subOpts = getSubOptions opts (path ++ [name]);
+        in
+          if subOpts != {}
+          then
+            wrapModule
+            (path ++ [name])
+            (
+              (recurse (path ++ [name]) subOpts)
+              // {
+                # This is necessary to include the submodule option's definition in the docs (description, type, etc.)
+                # For instance, this helps submodules like "autoCmd" to include their base definitions and examples in the docs
+                # Though there might be a better, less "hacky" solution than this.
+                ${name} = recursiveUpdate opts {
+                  isOption = true;
+                  type.getSubOptions = _: _: {}; # Used to exclude suboptions from the submodule definition itself
+                };
+              }
+            )
+            false
+          else wrapModule (path ++ [name]) opts true;
+    in
+      mapAttrs g mods;
+  in
+    foldlAttrs
+    (
+      acc: name: opts: let
+        group =
+          if !opts.hasComponents
+          then "Neovim Options"
+          else "none";
+
+        last =
+          acc.${group}
+          or {
+            index = {
+              options = {};
+              path = removeWhitespace "${group}";
+            };
+            components = {};
+            isGroup = true;
+            hasComponents = false;
+          };
+
+        isOpt = !opts.hasComponents && (isOption opts.index.options);
+      in
+        acc
+        // {
+          ${group} = recursiveUpdate last {
+            index.options = optionalAttrs isOpt {
+              ${name} = opts.index.options;
+            };
+
+            components = optionalAttrs (!isOpt) {
+              ${name} = recursiveUpdate opts {
+                index.path = removeWhitespace (concatStringsSep "/" ((optional (group != "none") group) ++ [opts.index.path]));
+                hasComponents = true;
+              };
+            };
+
+            hasComponents = last.components != {};
+          };
+        }
+    )
+    {}
+    (recurse [] modules);
+
+  mapModulesToString = f: modules: let
+    recurse = mods: let
+      g = name: opts:
+        if (opts ? "isGroup")
+        then
+          if name != "none"
+          then (f name opts) + ("\n" + recurse opts.components)
+          else recurse opts.components
+        else if opts.hasComponents
+        then (f name opts) + ("\n" + recurse opts.components)
+        else f name opts;
+    in
+      concatStringsSep "\n" (mapAttrsToList g mods);
+  in
+    recurse modules;
+
+  docs = rec {
+    modules = processModulesRec (removeUnwanted options.options);
+    commands =
+      mapModulesToString
+      (
+        name: opts: let
+          isBranch =
+            if (hasSuffix "index" opts.index.path)
+            then true
+            else opts.hasComponents;
+          path =
+            if isBranch
+            then "${opts.index.path}/index.md"
+            else "${opts.index.path}.md";
+        in
+          (optionalString isBranch
+            "mkdir -p ${opts.index.path}\n")
+          + "cp ${mkMDDoc opts.index.options} ${path}"
+      )
+      modules;
+  };
+
+  mdbook = {
+    nixvimOptions =
+      mapModulesToString
+      (
+        name: opts: let
+          isBranch =
+            if name == "index"
+            then true
+            else opts.hasComponents && opts.index.options != {};
+
+          path =
+            if isBranch
+            then "${opts.index.path}/index.md"
+            else if !opts.hasComponents
+            then "${opts.index.path}.md"
+            else "";
+
+          indentLevel = with builtins; length (filter isString (split "/" opts.index.path)) - 1;
+
+          padding = concatStrings (builtins.genList (_: "\t") indentLevel);
+        in "${padding}- [${name}](${path})"
+      )
+      docs.modules;
+  };
+
+  prepareMD = ''
+    # Copy inputs into the build directory
+    cp -r --no-preserve=all $inputs/* ./
+    cp ${../CONTRIBUTING.md} ./CONTRIBUTING.md
+
+    # Copy the generated MD docs into the build directory
+    # Using pkgs.writeShellScript helps to avoid the "bash: argument list too long" error
+    ${pkgs.writeShellScript "copy_docs" docs.commands}
+
+    # Prepare SUMMARY.md for mdBook
+    # Using pkgs.writeText helps to avoid the same error as above
+    substituteInPlace ./SUMMARY.md \
+      --replace "@NIXVIM_OPTIONS@" "$(cat ${pkgs.writeText "nixvim-options-summary.md" mdbook.nixvimOptions})"
+  '';
+in
+  pkgs.stdenv.mkDerivation {
+    name = "nixvim-docs";
+
+    phases = ["buildPhase"];
+
+    buildInputs = [pkgs.mdbook];
+    inputs = sourceFilesBySuffices ./. [".md" ".toml" ".js"];
+
+    buildPhase = ''
+      dest=$out/share/doc
+      mkdir -p $dest
+      ${prepareMD}
+      mdbook build
+      cp -r ./book/* $dest
+    '';
+  }

flake.nix

@@ -117,7 +117,7 @@
             };
           };
           packages = {
-            docs = pkgs-unfree.callPackage (import ./docs.nix) {
+            docs = pkgs-unfree.callPackage (import ./docs) {
               modules = nixvimModules;
             };
             runUpdates =

plugins/colorschemes/kanagawa.nix

@@ -76,7 +76,7 @@ in {
               Change specific usages for a certain theme, or for all of them
 
               Example:
-              ```
+              ```nix
                 {
                   wave = {
                     ui = {
@@ -103,7 +103,7 @@ in {
             Change all usages of these colors.
 
             Example:
-            ```
+            ```nix
               {
                 sumiInk0 = "#000000";
                 fujiWhite = "#FFFFFF";

plugins/completion/copilot-lua.nix

@@ -89,7 +89,7 @@ in {
             Each value can be either a boolean or a lua function that returns a boolean.
 
             Example:
-            ```
+            ```nix
               {
                 markdown = true; # overrides default
                 terraform = false; # disallow specific filetype
@@ -107,7 +107,7 @@ in {
 
             The key `"*"` can be used to disable the default configuration.
             Example:
-            ```
+            ```nix
               {
                 javascript = true; # allow specific filetype
                 typescript = true; # allow specific filetype
@@ -138,7 +138,7 @@ in {
           See `:h vim.lsp.start_client` for list of options.
 
           Example:
-          ```
+          ```nix
             {
               trace = "verbose";
               settings = {

plugins/completion/nvim-cmp/default.nix

@@ -126,7 +126,7 @@ in {
           - ultisnips
 
           You can also provide a custom function:
-          ```
+          ```nix
           {
             __raw = \'\'
               function(args)

plugins/dap/dap-ui.nix

@@ -122,7 +122,7 @@ in {
       layouts =
         helpers.defaultNullOpts.mkNullable (types.listOf layoutOption)
         ''
-          ```
+          ```nix
             [
               {
                 elements = [