Merge pull request #177 from NotAShelf/nixos-option-docs

docs: use nixosOptionDocs

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;};
 }

docs/man-configuration.xml

@@ -45,6 +45,6 @@
   <para>
    You can use the following options in your neovim configuration.
   </para>
-  <xi:include href="./nmd-result/neovim-flake-options.xml"/>
+  <xi:include href="./nmd-result/neovim-flake-options.xml" xpointer="neovim-flake-options"/>
  </refsection>
 </refentry>

docs/manual.xml

@@ -25,7 +25,6 @@
  <xi:include href="manual/hacking.xml"/>
  <appendix xml:id="ch-options">
   <title>Configuration Options</title>
-  <xi:include href="./nmd-result/neovim-flake-options.xml" />
+  <xi:include href="./nmd-result/neovim-flake-options.xml" xpointer="neovim-flake-options" />
  </appendix>
- <xi:include href="./release-notes/release-notes.xml" />
 </book>

docs/manual/hacking.adoc

@@ -144,6 +144,7 @@ For example:
 [source,nix]
 ----
 # parent modules should always be unfolded
+# which means module = { value = ... } instead of module.value = { ... }
 module = {
     value = mkEnableOption "some description" // { default = true; }; # merges can be done inline where possible
 
@@ -202,7 +203,7 @@ without any error messages (you can check the output of `:messages` inside neovi
 your changes are good to go. Open your pull request, and it will be reviewed as soon as posssible.
 
 If it is not a new module, but a change to an existing one, then make sure the module you have changed is enabled in the
-maximal configuration by editing configuration.nix, and then run it with `nix run .#maximal -Lv`. Same procedure as
+maximal configuration by editing `configuration.nix`, and then run it with `nix run .#maximal -Lv`. Same procedure as
 adding a new module will apply here.
 
 [[sec-keybinds]]

docs/release-notes/rl-0.5.adoc

@@ -74,6 +74,11 @@ https://github.com/notashelf[notashelf]:
 
 * Added `nvim-docs-view`, a plugin to display lsp hover documentation in a side panel
 
+* Switched to `nixosOptionsDoc` in option documentation.
+To quote home-manager commit: "Output is mostly unchanged aside from some minor typographical and
+formatting changes, along with better source links."
+
+
 https://github.com/jacekpoz[jacekpoz]:
 
 * Fixed scrollOffset not being used

lib/default.nix

@@ -3,6 +3,5 @@
   booleans = import ./booleans.nix {inherit lib;};
   types = import ./types {inherit lib;};
   languages = import ./languages.nix {inherit lib;};
-  nmd = import ./nmd.nix;
   lua = import ./lua.nix {inherit lib;};
 }

lib/stdlib-extended.nix

@@ -70,5 +70,4 @@ in
 
     # For forward compatibility.
     literalExpression = super.literalExpression or super.literalExample;
-    literalDocBook = super.literalDocBook or super.literalExample;
   })

lib/types/plugins.nix

@@ -112,6 +112,7 @@ with lib; let
       options = {
         package = mkOption {
           type = pluginType;
+          description = "Plugin Package.";
         };
         after = mkOption {
           type = listOf str;

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 {

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 [](#opt-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 = lib.literalMD ''
+            ```lua
             function(entry, vim_item)
               return vim_item
             end
-            ---
+            ```
           '';
         };
       };

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

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 = "│";

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 = {

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 [](#opt-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.

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

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 {

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 [](#opt-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>
         '';