docs: use nixosOptionDocs

NixOS 23.11 is deprecating DocBook option documentation. Following home-manager in this change is probably a good idea
NotAShelf · Nov 4, 2023 · 3de5f1b · 3de5f1b
1 parent e498331
commit 3de5f1b
Show file tree

Hide file tree

Showing 10 changed files with 91 additions and 30 deletions.
diff --git a/docs/default.nix b/docs/default.nix
@@ -29,25 +29,68 @@
     ];
   };
 
+  githubDeclaration = user: repo: subpath: let
+    urlRef = "main";
+  in {
+    url = "https://github.com/${user}/${repo}/blob/${urlRef}/${subpath}";
+    name = "<${repo}/${subpath}>";
+  };
+
   dontCheckDefinitions = {_module.check = false;};
 
-  nvimModuleDocs = nmd.buildModulesDocs {
+  nvimPath = toString ./..;
+
+  buildOptionsDocs = args @ {
+    modules,
+    includeModuleSystemsOptions ? true,
+    ...
+  }: let
+    options = (lib.evalModules {inherit modules;}).options;
+  in
+    pkgs.buildPackages.nixosOptionsDoc
+    ({
+        options =
+          if includeModuleSystemsOptions
+          then options
+          else builtins.removeAttrs (options ["_module"]);
+        transformOptions = opt:
+          opt
+          // {
+            # Clean up declaration sites to not refer to local source tree
+            declarations =
+              map
+              (decl:
+                if lib.hasPrefix nvimPath (toString decl)
+                then
+                  githubDeclaration "notashelf" "neovim-flake"
+                  (lib.removePrefix "/" (lib.removePrefix nvimPath (toString decl)))
+                else decl)
+              opt.declarations;
+          };
+      }
+      // builtins.removeAttrs args ["modules" "includeModuleSystemsOptions"]);
+
+  nvimModuleDocs = buildOptionsDocs {
     modules =
-      import ../modules/modules.nix {
+      import ../modules/modules.nix
+      {
         inherit pkgs lib;
         check = false;
       }
-      ++ [scrubbedPkgsModule dontCheckDefinitions];
-    moduleRootPaths = [./..];
-    mkModuleUrl = path: "https://github.com/notashelf/neovim-flake/blob/main/${path}#blob-path";
-    channelName = "neovim-flake";
-    docBook.id = "neovim-flake-options";
+      ++ [scrubbedPkgsModule];
+    variablelistId = "neovim-flake-options";
   };
 
   docs = nmd.buildDocBookDocs {
     pathName = "neovim-flake";
     projectName = "neovim-flake";
-    modulesDocs = [nvimModuleDocs];
+    modulesDocs = [
+      {
+        docBook = pkgs.linkFarm "nvim-module-docs-for-nmd" {
+          "nmd-result/neovim-flake-options.xml" = nvimModuleDocs.optionsDocBook;
+        };
+      }
+    ];
     documentsDirectory = ./.;
     documentType = "book";
     chunkToc = ''
@@ -65,7 +108,24 @@
     '';
   };
 in {
-  options.json = nvimModuleDocs.json.override {path = "share/doc/neovim-flake/options.json";};
-  manPages = docs.manPages;
+  options.json =
+    pkgs.runCommand "options.json"
+    # TODO: Use `nvimOptionsDoc.optionsJSON` directly once upstream
+    # `nixosOptionsDoc` is more customizable
+    {
+      meta.description = "List of neovim-flake options in JSON format";
+    } ''
+      mkdir -p $out/{share/doc,nix-support}
+      cp -a ${nvimModuleDocs.optionsJSON}/share/doc/nixos $out/share/doc/neovim-flake
+      substitute \
+       ${nvimModuleDocs.optionsJSON}/nix-support/hydra-build-products \
+       $out/nix-support/hydra-build-products \
+       --replace \
+        '${nvimModuleDocs.optionsJSON}/share/doc/nixos' \
+        "$out/share/doc/neovim-flake"
+    '';
+
+  inherit (docs) manPages;
+
   manual = {inherit (docs) html htmlOpenTool;};
 }
diff --git a/modules/autopairs/nvim-autopairs/nvim-autopairs.nix b/modules/autopairs/nvim-autopairs/nvim-autopairs.nix
@@ -15,7 +15,7 @@ with builtins; {
         map_cr = mkOption {
           type = types.bool;
           default = true;
-          description = nvim.nmd.asciiDoc ''map <CR> on insert mode'';
+          description = ''map <CR> on insert mode'';
         };
 
         map_complete = mkOption {

diff --git a/modules/completion/nvim-cmp/nvim-cmp.nix b/modules/completion/nvim-cmp/nvim-cmp.nix
@@ -22,7 +22,7 @@ with builtins; {
       };
 
       sources = mkOption {
-        description = nvim.nmd.asciiDoc ''
+        description = ''
           Attribute set of source names for nvim-cmp.
 
           If an attribute set is provided, then the menu value of
@@ -40,23 +40,22 @@ with builtins; {
 
       formatting = {
         format = mkOption {
-          description = nvim.nmd.asciiDoc ''
+          description = ''
             The function used to customize the appearance of the completion menu.
 
-            If <<opt-vim.lsp.lspkind.enable>> is true, then the function
+            If {option}`vim.lsp.lspkind.enable` is true, then the function
             will be called before modifications from lspkind.
 
             Default is to call the menu mapping function.
           '';
           type = types.str;
           default = "nvim_cmp_menu_map";
-          example = nvim.nmd.literalAsciiDoc ''
-            [source,lua]
-            ---
+          example = ''
+            ```lua
             function(entry, vim_item)
               return vim_item
             end
-            ---
+            ```
           '';
         };
       };

diff --git a/modules/core/default.nix b/modules/core/default.nix
@@ -27,23 +27,23 @@ with builtins; let
   mapConfigOptions = {
     silent =
       mkBool false
-      (nvim.nmd.asciiDoc "Whether this mapping should be silent. Equivalent to adding <silent> to a map.");
+      "Whether this mapping should be silent. Equivalent to adding <silent> to a map.";
 
     nowait =
       mkBool false
-      (nvim.nmd.asciiDoc "Whether to wait for extra input on ambiguous mappings. Equivalent to adding <nowait> to a map.");
+      "Whether to wait for extra input on ambiguous mappings. Equivalent to adding <nowait> to a map.";
 
     script =
       mkBool false
-      (nvim.nmd.asciiDoc "Equivalent to adding <script> to a map.");
+      "Equivalent to adding <script> to a map.";
 
     expr =
       mkBool false
-      (nvim.nmd.asciiDoc "Means that the action is actually an expression. Equivalent to adding <expr> to a map.");
+      "Means that the action is actually an expression. Equivalent to adding <expr> to a map.";
 
     unique =
       mkBool false
-      (nvim.nmd.asciiDoc "Whether to fail if the map is already defined. Equivalent to adding <unique> to a map.");
+      "Whether to fail if the map is already defined. Equivalent to adding <unique> to a map.";
 
     noremap =
       mkBool true

diff --git a/modules/filetree/nvimtree/nvimtree.nix b/modules/filetree/nvimtree/nvimtree.nix
@@ -580,6 +580,7 @@ with builtins; {
 
             icons = mkOption {
               type = types.attrs;
+              description = "Individual elements of the indent markers";
               default = {
                 corner = "└";
                 edge = "│";

diff --git a/modules/statusline/lualine/lualine.nix b/modules/statusline/lualine/lualine.nix
@@ -84,7 +84,7 @@ in {
         default = "auto";
         # TODO: xml generation error if the closing '' is on a new line.
         # issue: https://gitlab.com/rycee/nmd/-/issues/10
-        defaultText = nvim.nmd.literalAsciiDoc ''`config.vim.theme.name` if theme supports lualine else "auto"'';
+        defaultText = ''`config.vim.theme.name` if theme supports lualine else "auto"'';
       };
 
     sectionSeparator = {

diff --git a/modules/treesitter/context.nix b/modules/treesitter/context.nix
@@ -37,7 +37,7 @@ in {
     };
 
     trimScope = mkOption {
-      description = nvim.nmd.asciiDoc "Which context lines to discard if <<opt-vim.treesitter.context.maxLines>> is exceeded.";
+      description = "Which context lines to discard if {option}`vim.treesitter.context.maxLines` is exceeded.";
       type = types.enum ["inner" "outer"];
       default = "outer";
     };
@@ -49,7 +49,7 @@ in {
     };
 
     separator = mkOption {
-      description = nvim.nmd.asciiDoc ''
+      description = ''
         Separator between context and content. Should be a single character string, like '-'.
 
         When separator is set, the context will only show up when there are at least 2 lines above cursorline.

diff --git a/modules/treesitter/treesitter.nix b/modules/treesitter/treesitter.nix
@@ -19,7 +19,7 @@ with lib; {
     grammars = mkOption {
       type = with types; listOf package;
       default = [];
-      description = nvim.nmd.asciiDoc ''
+      description = ''
         List of treesitter grammars to install. For supported languages
         use the `vim.language.<lang>.treesitter` option
       '';

diff --git a/modules/ui/breadcrumbs/breadcrumbs.nix b/modules/ui/breadcrumbs/breadcrumbs.nix
@@ -305,6 +305,7 @@ in {
         reorient = mkOption {
           type = types.enum ["smart" "top" "mid" "none"];
           default = "smart";
+          description = "reorient buffer after changing nodes";
         };
 
         scrolloff = mkOption {

diff --git a/modules/visuals/visuals.nix b/modules/visuals/visuals.nix
@@ -80,8 +80,8 @@ in {
       };
 
       showEndOfLine = mkOption {
-        description = nvim.nmd.asciiDoc ''
-          Displays the end of line character set by <<opt-vim.visuals.indentBlankline.eolChar>> instead of the
+        description = ''
+          Displays the end of line character set by {option}`vim.visuals.indentBlankline.eolChar` instead of the
           indent guide on line returns.
         '';
         type = types.bool;
@@ -110,7 +110,7 @@ in {
       highlightForCount = mkOption {
         type = types.bool;
         default = true;
-        description = nvim.nmd.literalAsciiDoc ''
+        description = ''
           Enable support for highlighting when a <count> is provided before the key
           If set to false it will only highlight when the mapping is not prefixed with a <count>
         '';