docs: Add basic documentation system based on nmd

You can now run `nix build '.#docs'` to build HTML documentation
documenting every single option on nixvim! Fortunately, thanks to
the 'description' field, most options are already documented, but
there are still a fair few that need documenting.

I will be taking care of those in the next few days. When those are
done, I will find a way to automatically rebuild documentation on every
repo push, and also add a PR hook requiring documentation.

Additionally, I will try to find a way to have per-page plugin docs.

.gitignore

@@ -1 +1,2 @@
 .tmp
+result

docs/default.nix

@@ -0,0 +1,51 @@
+{ pkgs, lib, ... }:
+let
+  nmdSrc = pkgs.fetchFromGitLab {
+    name = "nmd";
+    owner = "rycee";
+    repo = "nmd";
+    rev = "527245ff605bde88c2dd2ddae21c6479bb7cf8aa";
+    sha256 = "1zi0f9y3wq4bpslx1py3sfgrgd9av41ahpandvs6rvkpisfsqqlp";
+  };
+  nmd = import nmdSrc { inherit pkgs lib; };
+  scrubbedPkgsModule = {
+    imports = [{
+      _module.args = {
+        pkgs = lib.mkForce (nmd.scrubDerivations "pkgs" pkgs);
+        pkgs_i686 = lib.mkForce { };
+      };
+    }];
+  };
+  buildModulesDocs = args:
+    nmd.buildModulesDocs ({
+      moduleRootPaths = [ ./.. ];
+      mkModuleUrl = path:
+        "https://github.com/pta2002/nixvim/blob/master/${path}#blob-path";
+      channelName = "nixvim";
+    } // args);
+  nixvimDocs = buildModulesDocs {
+    modules = [
+      (import ../nixvim.nix {})
+      scrubbedPkgsModule
+    ];
+    docBook.id = "nixvim-options";
+  };
+
+  docs = nmd.buildDocBookDocs {
+    pathName = "";
+    modulesDocs = [ nixvimDocs ];
+    documentsDirectory = ./.;
+    documentType = "book";
+    chunkToc = ''
+    <toc>
+      <d:tocentry xmlns:d="http://docbook.org/ns/docbook" linkend="book-home-manager-manual"><?dbhtml filename="index.html"?>
+        <d:tocentry linkend="ch-options"><?dbhtml filename="options.html"?></d:tocentry>
+        <d:tocentry linkend="ch-nixos-options"><?dbhtml filename="nixos-options.html"?></d:tocentry>
+        <d:tocentry linkend="ch-nix-darwin-options"><?dbhtml filename="nix-darwin-options.html"?></d:tocentry>
+        <d:tocentry linkend="ch-tools"><?dbhtml filename="tools.html"?></d:tocentry>
+        <d:tocentry linkend="ch-release-notes"><?dbhtml filename="release-notes.html"?></d:tocentry>
+      </d:tocentry>
+      </toc>
+    '';
+  };
+in docs.html

docs/man-nixvim.xml

@@ -0,0 +1,27 @@
+<refentry xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+ <refmeta>
+  <refentrytitle><filename>nixvim.nix</filename></refentrytitle>
+  <manvolnum>5</manvolnum>
+  <refmiscinfo class="source">NixVim</refmiscinfo>
+<!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> -->
+ </refmeta>
+ <refnamediv>
+  <refname><filename>nixvim.nix</filename></refname>
+  <refpurpose>NixVim configuration specification</refpurpose>
+ </refnamediv>
+ <refsection>
+  <title>Description</title>
+  <para>
+    TODO
+  </para>
+ </refsection>
+ <refsection>
+  <title>Options</title>
+  <para>
+   You can use the following options in your nixvim config
+  </para>
+  <xi:include href="./nmd-result/nixvim-options.xml" />
+ </refsection>
+</refentry>

docs/man-pages.xml

@@ -0,0 +1,11 @@
+<reference xmlns="http://docbook.org/ns/docbook"
+           xmlns:xlink="http://www.w3.org/1999/xlink"
+           xmlns:xi="http://www.w3.org/2001/XInclude">
+ <title>NixVim Reference Pages</title>
+ <info>
+  <author><personname>NixVim contributors</personname></author>
+  <copyright><year>2021-2022</year><holder>NixVim contributors</holder>
+  </copyright>
+ </info>
+ <xi:include href="man-nixvim.xml" />
+</reference>

docs/manual.xml

@@ -0,0 +1,23 @@
+<book xmlns="http://docbook.org/ns/docbook"
+  xmlns:xlink="http://www.w3.org/1999/xlink"
+  xmlns:xi="http://www.w3.org/2001/XInclude"
+  version="5.0"
+  xml:id="book-home-manager-manual">
+  <info>
+    <title>NixVim Manual</title>
+  </info>
+  <preface>
+    <title>Preface</title>
+    <para>
+      This manual is meant to serve as the ultimate reference for how to use and install NixVim.
+    </para>
+    <para>
+      If you have any issues, questions, or plugin suggestions please open an issue on the
+      <link xlink:href="https://github.com/pta2002/nixvim">NixVim GitHub</link>
+    </para>
+  </preface>
+  <appendix xml:id="ch-options">
+    <title>Configuration Options</title>
+    <xi:include href="./nmd-result/nixvim-options.xml" />
+  </appendix>
+</book>

flake.lock

@@ -2,11 +2,11 @@
   "nodes": {
     "nixpkgs": {
       "locked": {
-        "lastModified": 1638986258,
-        "narHash": "sha256-OceRdctKZRSgqQxVRvvNB0MaEnFMzQqjUffecoDE9eI=",
+        "lastModified": 1641710811,
+        "narHash": "sha256-yVJ+CtwWZY8BnkNIJ/ue5a28yrRM6CkDF1LvmGmqqwM=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "581d2d6c9cd5c289002203581d8aa0861963a933",
+        "rev": "0ecf7d414811f831060cf55707c374d54fbb1dec",
         "type": "github"
       },
       "original": {
@@ -16,9 +16,26 @@
         "type": "github"
       }
     },
+    "nmdSrc": {
+      "flake": false,
+      "locked": {
+        "lastModified": 1637239786,
+        "narHash": "sha256-l2KsnY537mz0blZdqALZKrWXn9PD39CpvotgPnxyIP4=",
+        "owner": "rycee",
+        "repo": "nmd",
+        "rev": "527245ff605bde88c2dd2ddae21c6479bb7cf8aa",
+        "type": "gitlab"
+      },
+      "original": {
+        "owner": "rycee",
+        "repo": "nmd",
+        "type": "gitlab"
+      }
+    },
     "root": {
       "inputs": {
-        "nixpkgs": "nixpkgs"
+        "nixpkgs": "nixpkgs",
+        "nmdSrc": "nmdSrc"
       }
     }
   },

flake.nix

@@ -3,7 +3,15 @@
 
   inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
 
-  outputs = { self, nixpkgs, ... }@inputs: rec {
+  inputs.nmdSrc.url = "gitlab:rycee/nmd";
+  inputs.nmdSrc.flake = false;
+
+  outputs = { self, nixpkgs, nmdSrc, ... }@inputs: rec {
+    packages."x86_64-linux".docs = import ./docs {
+      pkgs = import nixpkgs { system = "x86_64-linux"; };
+      lib = nixpkgs.lib;
+    };
+
     nixosModules.nixvim = import ./nixvim.nix { nixos = true; };
     homeManagerModules.nixvim = import ./nixvim.nix { homeManager = true; };
 

nixvim.nix

@@ -1,5 +1,5 @@
 { nixos ? false, nixOnDroid ? false, homeManager ? false }:
-{ pkgs, lib, config, ... }:
+{ pkgs , lib, config, ... }:
 with lib;
 let
   cfg = config.programs.nixvim;
@@ -100,8 +100,9 @@ in
       };
 
       colorscheme = mkOption {
-        type = types.str;
+        type = types.nullOr types.str;
         description = "The name of the colorscheme";
+        default = null;
       };
 
       extraConfigLua = mkOption {
@@ -126,6 +127,7 @@ in
       configure = mkOption {
         type = types.attrsOf types.anything;
         default = { };
+        description = "Internal option";
       };
 
       options = mkOption {
@@ -257,7 +259,7 @@ in
 
   in mkIf cfg.enable (if nixos then {
     environment.systemPackages = [ wrappedNeovim ];
-    programs.nixvim = {
+    programs.neovim = {
       configure = configure;
 
       extraConfigLua = extraConfigLua;
@@ -273,14 +275,5 @@ in
       extraConfig = configure.customRC;
       plugins = cfg.extraPlugins;
     };
-  } else {
-    environment.packages = [ wrappedNeovim ];
-    programs.nixvim = {
-      configure = configure;
-
-      extraConfigLua = extraConfigLua;
-    };
-
-    environment.etc."xdg/nvim/sysinit.vim".text = neovimConfig.neovimRcContent;
-  }));
+  } else {}));
 }

plugins/git/gitgutter.nix

@@ -91,7 +91,7 @@ in {
       };
 
       grep = mkOption {
-        type = types.nullOr (types.oneOf [ types.submodule {
+        type = types.nullOr (types.oneOf [ (types.submodule {
           options = {
             command = mkOption {
               type = types.str;
@@ -103,7 +103,7 @@ in {
               description = "The package of the grep alternative to use";
             };
           };
-        } types.str]);
+        }) types.str]);
         default = null;
         description = "A non-standard grep to use instead of the default";
       };

plugins/statuslines/airline.nix

@@ -30,12 +30,14 @@ in {
       sections = mkOption {
         default = null;
         type = with types; nullOr (submodule {
-          a = sectionOption;
-          b = sectionOption;
-          c = sectionOption;
-          x = sectionOption;
-          y = sectionOption;
-          z = sectionOption;
+          options = {
+            a = sectionOption;
+            b = sectionOption;
+            c = sectionOption;
+            x = sectionOption;
+            y = sectionOption;
+            z = sectionOption;
+          };
         });
       };
 

plugins/statuslines/lightline.nix

@@ -21,7 +21,7 @@ in {
         description = ''
           A list of function component definitions.
 
-          You should define the functions themselves in <para>extraConfig</para>
+          You should define the functions themselves in extraConfig
         '';
         example = ''
           programs.nixvim.plugins.lightline = {

plugins/utils/comment-nvim.nix

@@ -64,8 +64,7 @@ in
           options = {
             basic = mkOption {
               type = types.bool;
-              description = "operator-pending mapping. Includes 'gcc', 'gcb', 'gc[count]{motion}' 
-              and 'gb[count]{motion}'";
+              description = "operator-pending mapping. Includes 'gcc', 'gcb', 'gc[count]{motion}' and 'gb[count]{motion}'";
               default = true;
             };
             extra = mkOption {
@@ -75,8 +74,7 @@ in
             };
             extended = mkOption {
               type = types.bool;
-              description = "extended mapping. Includes 'g>', 'g<', 'g>[count]{motion}' and 
-              'g<[count]{motion}'";
+              description = "extended mapping. Includes 'g&gt;', 'g&lt;', 'g&gt;[count]{motion}' and 'g&lt;[count]{motion}'";
               default = false;
             };
           };

plugins/utils/floaterm.nix

@@ -23,12 +23,12 @@ in
       };
       winWidth = mkOption {
         type = types.nullOr types.float;
-        description = "number of columns relative to &columns.";
+        description = "number of columns relative to &columns.";
         default = null;
       };
       winHeight = mkOption {
         type = types.nullOr types.float;
-        description = "number of lines relative to &lines.";
+        description = "number of lines relative to &lines.";
         default = null;
       };
       borderChars = mkOption {
@@ -38,7 +38,7 @@ in
       };
       rootMarkers = mkOption {
         type = types.nullOr (types.listOf types.str);
-        description = "Markers used to detect the project root directory for --cwd=<root>";
+        description = "Markers used to detect the project root directory for --cwd=&lt;root&gt;";
         default = null;
       };
       opener = mkOption {

plugins/utils/startify.nix

@@ -17,23 +17,25 @@ mkPlugin args {
     lists = mkDefaultOpt {
       description = "Startify display lists. If it's a string, it'll be interpreted as literal lua code";
       global = "startify_lists";
-      type = types.listOf (types.oneOf [types.submodule {
-        type = mkOption {
-          type = types.str;
-          description = "The type of the list";
+      type = types.listOf (types.oneOf [(types.submodule {
+        options = {
+          type = mkOption {
+            type = types.str;
+            description = "The type of the list";
+          };
+          # TODO the header should be a literal lua string!
+          header = mkOption {
+            type = types.nullOr (types.listOf types.str);
+            description = "Optional header. It's a list of strings";
+            default = null;
+          };
+          indices = mkOption {
+            type = types.nullOr (types.listOf types.str);
+            description = "Optional indices for the current list";
+            default = null;
+          };
         };
-        # TODO the header should be a literal lua string!
-        header = mkOption {
-          type = types.nullOr (types.listOf types.str);
-          description = "Optional header. It's a list of strings";
-          default = null;
-        };
-        indices = mkOption {
-          type = types.nullOr (types.listOf types.str);
-          description = "Optional indices for the current list";
-          default = null;
-        };
-      } types.str]);
+      }) types.str]);
 
       value = val: let
         list = map (v: if builtins.isAttrs v then toLuaObject v else v) val;
@@ -131,7 +133,7 @@ mkPlugin args {
     };
 
     enableSpecial = mkDefaultOpt {
-      description = "Show <empty buffer> and <quit>";
+      description = "Show &lt;empty buffer&gt; and &lt;quit&gt;";
       global = "startify_enable_special";
       type = types.bool;
     };